GitHub Actions Not Running in Private Repos on Free Tier? An Engineering Project Management Insight

Reliable CI/CD workflows are a cornerstone of effective engineering project management, ensuring code quality and efficient delivery. When these critical automations fail to run, it can significantly impact team productivity and project timelines. A recent discussion on GitHub Community highlighted a common, yet perplexing, issue: GitHub Actions workflows failing to trigger in private repositories on a GitHub Free account.

The Problem: Workflows Not Running, No Checks, No Errors

Developer fro0ty155 encountered a scenario where a newly committed workflow, .github/workflows/ci.yml, on a feature branch (setup/ci-bootstrap) in a private repository, produced no runs on the Actions page and no checks on the associated pull request. Crucially, there were no error messages or failed runs to inspect, making diagnosis difficult.

The workflow's trigger configuration was standard:

name: CI
on:
  push:
    branches: [setup/ci-bootstrap]
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

Fro0ty155 had already performed several checks:

• Repository Actions were enabled, with no custom policies.
• The PR was from a branch within the same repository, not a fork.
• Commits were made as the owner, not via GITHUB_TOKEN.
• The included Actions allowance was almost unused.

Expert Diagnostics: Uncovering Hidden Restrictions

Community expert Sagargupta16 provided a comprehensive diagnostic path, clarifying that for push and pull_request events, a workflow does not need to be on the default branch to trigger. This is a crucial distinction, as some other event types (like schedule or workflow_dispatch) do require the workflow to be present on the default branch.

The key to diagnosing such issues lies in using the GitHub API (via gh api or curl with a PAT) to inspect the repository's state from GitHub's perspective:

1. Repository-level Actions state: Verify Actions are truly enabled. Expected output: "enabled": true.

   gh api repos/OWNER/REPO/actions/permissions

2. Registered Workflows: Check if GitHub has recognized your workflow file and its state.

   gh api repos/OWNER/REPO/actions/workflows --jq '.workflows[] | {name, path, state}'

3. Hidden Runs: Look for any runs the UI might be filtering or hiding.

   gh api "repos/OWNER/REPO/actions/runs?branch=setup/ci-bootstrap" --jq '.total_count'
   gh api "repos/OWNER/REPO/actions/runs?event=pull_request" --jq '.total_count'

4. The Real Discriminator: Check Suites: This is the most telling diagnostic. Every pushed commit should get a github-actions check suite if a run is created. If this is missing entirely, the event never even produced a run.

   gh api repos/OWNER/REPO/commits/HEAD_SHA/check-suites \
   --jq '.check_suites[] | select(.app.slug=="github-actions") | {status, conclusion, latest_check_runs_count}'

The Account-Level Restriction

If diagnostics 1 and 2 show everything is enabled and the workflow is registered, but diagnostic 4 reveals no github-actions check suite for the relevant commits, the problem is likely an account-level restriction. This is particularly common on newly created personal GitHub Free accounts.

To confirm this, Sagargupta16 suggested a quick control test:

• Create a throwaway public repository on the same GitHub account.
• Commit a simple on: push workflow through the web editor.
• Check the Actions tab. If no run appears there either, the account is indeed restricted.

Such restrictions are not visible through any repository settings or API responses and can only be seen and lifted by GitHub Support (https://support.github.com, category Actions). Billing is rarely the cause if your allowance is largely untouched.

Conclusion for Effective Engineering Project Management

While ensuring your workflow files are correctly placed and configured is fundamental for any engineering project management software, sometimes the issue lies beyond the repository's immediate settings. When GitHub Actions workflows fail to run without error, especially on a Free account, an invisible account-level restriction is a strong possibility. Leveraging API diagnostics and a simple control test can quickly pinpoint the root cause, guiding you to the correct resolution path with GitHub Support, and getting your automated workflows back on track.