Diagnosing Missing GitHub Actions Runs on Push or Pull Request

Recognizable condition

You have a workflow file under .github/workflows/ but after a push or pull_request event:

• No run appears in the Actions tab,
• A run appears but is marked skipped, cancelled, or remains queued indefinitely.

In most cases the problem lies in trigger configuration or event‑source rules, not in the job steps themselves.

Cause & diagnostic table

Symptom	Likely cause	What to look for
No run on push	Workflow file missing from the pushed commit or invalid YAML	Check that .github/workflows/<file>.yml exists at the exact commit SHA and parses as YAML.
No run on fork PR	Actions disabled for forks or pending maintainer approval	Visit Settings → Actions → General and see if fork PRs are allowed; look for a yellow banner awaiting approval.
Run skipped	Paths/branches filter or a [skip ci]-style tag in the commit message	Inspect the on: block for branches or paths; check the latest commit message for skip tokens.
Run queued forever	No self‑hosted runner with required labels or a billing spending limit reached	Look at the run’s queue status; verify runner labels in Settings → Actions → Runners; check billing usage.
Run cancelled instantly	Concurrency group with cancel-in-progress: true	Find a concurrency: key in the workflow; note if a previous run is still active.

Ordered checks

1. Verify file presence and YAML validity
   • Where to run: your local clone or via the API.
   • Command (needs read access to the repo):

     git show <commit‑SHA>:.github/workflows/ci.yml

   • If the command returns fatal: Path '.github/workflows/ci.yml' does not exist in <commit‑SHA> the file is absent from that ref.
   • If the file appears but GitHub shows an “Invalid workflow file” annotation, run a YAML linter locally (e.g., yamllint ci.yml) to catch syntax errors.
2. Confirm the file is on the ref that fired the event
   • For a push, GitHub uses the pushed commit; for a schedule it uses the default branch.
   • Check the ref with:

     git rev-parse <branch-name>

     and compare to the commit that triggered the Action.
3. Read the on: block
   • Look for branches:, branches-ignore:, paths:, paths-ignore:, and the event types (push, pull_request).
   • Remember: paths on push evaluates the files changed in that push; on pull_request it evaluates the diff between the base and head.
4. Identify the event source and recursion guard
   • Pushes made with the default GITHUB_TOKEN by another workflow do not trigger new runs (recursion guard).
   • If the commit message contains [skip ci], [ci skip], [skip actions], or [actions skip], GitHub ignores the event.
5. Check repository‑level settings
   • Navigate to Settings → Actions → General.
   • Ensure Allow GitHub Actions to run is enabled.
   • For fork PRs, verify Enable read and write permissions for forks and that first‑time contributor approval is not pending.
6. Inspect the run state
   • Open the run from the Actions tab.
   • Note the top‑left badge: Queued, In progress, Completed, Cancelled, or Skipped.
   • If queued, check the runner labels required by the job (runs-on:) against the list of online runners (Settings → Actions → Runners).
   • If cancelled instantly, look for a concurrency: block with cancel-in-progress: true.

Fixes tied to findings

• File missing or invalid YAML – Add or correct the workflow file on the target branch, then push a commit that includes it. If the file exists but is malformed, fix the YAML and push the correction.
• Paths/branches filter too restrictive – Widen the filter (e.g., change paths: ['src/**'] to paths: ['**']) or remove it entirely, then push a trivial change to test.
• Skip‑CI token in commit message – Amend the commit (git commit --amend) or push a new commit without the skip token.
• Fork PR Actions disabled – In the repository settings enable Actions for fork PRs, or have a maintainer approve the pending run via the yellow banner.
• No matching runner – Add a self‑hosted runner with the required labels (runs-on: [self‑hosted, linux, large]) or change the job to use a GitHub‑hosted runner (ubuntu-latest).
• Billing limit reached – Increase the spending limit under Settings → Billing & plans → Actions billing or wait for the next billing cycle.
• Concurrency cancelling runs – Adjust the concurrency block (e.g., set cancel-in-progress: false) or use a unique concurrency key per workflow.

Isolation technique

Add a workflow_dispatch trigger to the same workflow:

on:
  workflow_dispatch:
  push:
    branches: [main]

Manually run the workflow from the Actions tab. If the manual run succeeds but the automatic push does not, the problem is trigger configuration, not the job contents.

Escalation criteria

Escalate to GitHub Support when:

• A run stays queued while the repository’s runners show as online and the Actions billing allowance has not been exhausted.
• The Actions tab itself displays an error or fails to load workflow runs.
• Behavior contradicts the documented trigger rules after you have reproduced the issue with a minimal workflow (e.g., a simple echo hello step).

Before opening a ticket, verify there is no ongoing incident on the GitHub Status page. Include the following in your support request:

• Repository name and owner.
• Run ID or commit SHA that should have triggered the workflow.
• UTC timestamps of the push/PR event and the time you checked the Actions tab.
• A copy of the minimal workflow file used for reproduction.
• Any relevant settings screenshots (Actions permissions, fork settings, runner labels).

---

This guide targets github.com. On GitHub Enterprise Server the behavior may differ regarding skip‑CI strings, fork‑PR approval defaults, and runner availability; consult your enterprise’s release notes for version‑specific details.