We earn commissions when you shop through the links below, at no extra cost to you. Our guides and technical recommendations are written independently of these relationships: a commission never decides what we recommend, how we diagnose a problem or what we publish, and the content does not depend on it. Affiliate disclosure

CI/CD · Beginner · 12 min

Fix a GitHub Actions workflow that never runs

Fix a GitHub Actions workflow that never runs: a file GitHub cannot see, branch and paths filters, [skip ci], the default branch, and suppressed events.

A workflow that never runs leaves no error behind. This runbook checks whether GitHub registered the file, whether the event matched the trigger, which branch the event reads the file from, and which events GitHub suppresses. Results come from a throwaway repository on GitHub.com, read back through the REST API.

See it run

A short replay of real output from commands in this guide, captured on a WSL2 Ubuntu test machine (a throwaway public repository on GitHub.com, read with git and the GitHub REST API). The typing is replayed, and the host name, account and MAC addresses are redacted. Your output will differ, and a test machine is not a production server.

Text version of this demo
ops@web-01:~$ git ls-files .github
.github/workflow/singular.yml
.github/workflows/branch-filter.yml
.github/workflows/manual.yml
.github/workflows/paths-filter.yml
.github/workflows/runs-on-push.yml
.github/workflows/sub/nested.yml

ops@web-01:~$ curl -s "$API/actions/workflows" | jq -r '.workflows[].path'
.github/workflows/branch-filter.yml
.github/workflows/feature-ci.yml
.github/workflows/manual.yml
.github/workflows/paths-filter.yml
.github/workflows/runs-on-push.yml

ops@web-01:~$ sed -n '/^on:/,/^jobs:/p' .github/workflows/branch-filter.yml
on:
  push:
    branches: [master]
jobs:

ops@web-01:~$ git log -3 --format='%H %s' origin/main | while read sha msg; do echo "$(curl -s "$API/actions/runs?head_sha=$sha" | jq .total_count) run(s): $msg"; done
0 run(s): Change app [skip ci]
1 run(s): Update docs only
2 run(s): Add test workflows

A workflow that fails at least leaves a red run behind. A workflow that never runs leaves nothing: no run, no log, no error. There are only a few reasons. GitHub did not find the file (or found it and could not parse it, which leaves a run with no jobs), the event did not match the trigger, the file is not on the branch that event reads, or GitHub suppressed the event. This runbook checks them in that order, from the outside, without guessing.

The results below come from test runs on 2026-11-16 on GitHub.com (GitHub-hosted runners), on an Ubuntu 26.04 test machine; the commands are not distribution-specific, and we did not run them on RHEL, AlmaLinux or Rocky. There were three setups, none named here. (A) An earlier run in a throwaway scratch repository, on a test branch called obf-lab: file discovery, the invalid file, the branch filter, the paths filter and [skip ci]. (B) A private repository with an existing workflow on its default branch, on a test branch called obf-test: the same file-discovery, filter and invalid-file tests again, plus the skip words, the skip-checks trailer, the timing in section 5, disabled_manually, git revert and pull_request. Where the two runs differ, the page says so. (C) A second run in that private repository for section 3 (push on a feature branch, workflow_dispatch, schedule). Runs were read back through the GitHub REST API. Section 4 and "What we have not verified" list what was not tested.

Why a workflow leaves no run behind1. GitHub finds the file (directly in .github/workflows/, .yml or .yaml, valid YAML (section 1)) Then 2. The event matches the trigger (event type, branches and paths filters (section 2)) Then 3. The file is on the right branch (each event reads the file from its own place (section 3)) Then 4. The event is not suppressed (GITHUB_TOKEN events, fork approval, conflicts, disabled (section 4)) Then 5. A run appears (a push, then gh run list).GitHub findsthe filedirectly in .github/workflows/, .yml or .yaml,valid YAML(section 1)The eventmatches thetriggerevent type,branches andpaths filters(section 2)The file is onthe rightbrancheach event readsthe file from itsown place(section 3)The event isnot suppressedGITHUB_TOKENevents, forkapproval,conflicts,disabled (section4)A run appearsa push, then ghrun list
Check in this order. Each step rules out one reason, from the outside in, without guessing.

0. Rules of engagement

  1. Change one thing per test commit. Trigger rules combine, and two changes at once make the result impossible to read.
  2. Read before you edit. Sections 1 to 3 only look at files and at what GitHub registered.
  3. Do not add on: push everywhere to make something happen. It can start deployments or other workflows that were never meant to run on every push.

1. Did GitHub find the file?

The GitHub documentation says workflow files must be directly in .github/workflows/, with a .yml or .yaml extension. In our tests, a file in the singular folder .github/workflow/ and a file in a subfolder (.github/workflows/sub/) never started a run, never showed an error and never appeared in the API list.

# The workflow files in the repository, then the ones GitHub registered (public repository; for a private one use gh api repos/OWNER/REPO/actions/workflows with the same jq filter)
git ls-files .github
curl -s https://api.github.com/repos/OWNER/REPO/actions/workflows | jq -r '.workflows[] | "\(.path)  \(.state)"'
# Real output from the test repository (setup A, earlier run in a scratch repository, test branch): six files, four registered
.github/workflow/singular.yml
.github/workflows/branch-filter.yml
.github/workflows/manual.yml
.github/workflows/paths-filter.yml
.github/workflows/runs-on-push.yml
.github/workflows/sub/nested.yml
.github/workflows/branch-filter.yml  active
.github/workflows/manual.yml  active
.github/workflows/paths-filter.yml  active
.github/workflows/runs-on-push.yml  active

singular.yml and sub/nested.yml are missing from the second list. In setup A, branch-filter and manual were already on the default branch and were listed before the test; paths-filter and runs-on-push were listed only after they had been pushed and had run. We did not look into why.

The same test in setup B (a private repository, so gh api instead of curl) behaved differently. The six files (plus the repository's own infra.yml) were pushed to a new branch, and the registered list is what the API returned:

# Real output from the test repository (setup B), shortened to the API lists: right after the push, 8 seconds later, and after the runs finished
--- API list immediately after push (t+0)
.github/workflows/infra.yml  active
total_count: 1
--- API list at t+8 s
.github/workflows/infra.yml  active
.github/workflows/obf-paths-filter.yml  active
.github/workflows/obf-runs-on-push.yml  active
--- API list after the runs finished (t+12 s)
.github/workflows/infra.yml  active
.github/workflows/obf-paths-filter.yml  active
.github/workflows/obf-runs-on-push.yml  active
total_count: 3

An observation, not a rule: on that non-default branch only the two files that actually ran were registered. obf-branch-filter (valid, but its filter did not match) and obf-manual (valid, workflow_dispatch only) were never listed, and neither were the singular-folder and subfolder files. So "listed in the API" cannot be the check for a valid file on a branch that has not run yet: a missing entry means the file has not produced a run, which can be a wrong folder or a trigger that did not match. We did not look into why.

The state column matters too. Setup B confirmed disabled_manually: after gh workflow disable obf-runs-on-push.yml the API listed disabled_manually, a push gave 0 runs, and after gh workflow enable obf-runs-on-push.yml the state was active and the next push gave 1 run. We used the CLI, not the Enable workflow button in the Actions tab. disabled_inactivity (GitHub switching off a schedule, section 3) was not tested.

If the Actions tab says that Actions are disabled, or shows no workflows at all, check Settings → Actions → General in the repository and the organization policy. This is from the GitHub documentation; we did not test it.

The file is found but invalid

A file that GitHub registers can still be invalid YAML. Then a run does appear, but it has no jobs and no log, and it shows the file path where the workflow name: should be. This is the one case in this runbook that leaves a red run behind, and it is easy to take for a workflow that never ran.

# Read-only: the run summary, its log (RUN_ID comes from gh run list), then a local YAML parse of the file
gh run view RUN_ID
gh run view RUN_ID --log
python3 -c 'import sys, yaml; yaml.safe_load(open(sys.argv[1]))' .github/workflows/FILE.yml
# Real output from the test repository (setup B, gh 2.46.0), shortened: RUN_ID masked, the Python command written in short form, the traceback cut to its last lines
$ cat -n .github/workflows/obf-deploy.yml
     1	name: obf-test
     2	on:
     3	  push:
     4	    branches: [obf-test]
     5	jobs:
     6	  deploy:
     7	    runs-on: ubuntu-latest
     8	    steps:
     9	      - uses: actions/checkout@v4
    10	      - run: echo "Commit message: hello"
$ gh run view RUN_ID

X obf-test .github/workflows/obf-deploy.yml · RUN_ID
Triggered via push less than a minute ago

X This run likely failed because of a workflow file issue.

For more information, see: https://github.com/OWNER/REPO/actions/runs/RUN_ID
$ gh run view RUN_ID --log
failed to get run log: log not found
$ python3 -c yaml.safe_load obf-deploy.yml
yaml.scanner.ScannerError: mapping values are not allowed here
  in ".github/workflows/obf-deploy.yml", line 10, column 34

The line number depends on the file: it is line 10 of the file printed above (the same test in setup A gave the same message). In our test the failing line was an unquoted run: echo "Commit message: hello": the : inside a plain YAML value is what the parser rejected. Writing the command as a block scalar (run: | and the command on the next line) is the usual fix; we did not re-run that fix in the 2026-11-16 test. The same run also showed in the API with the file path as the workflow name (.github/workflows/obf-deploy.yml). Change one thing per commit here as well, so the run that starts is the one you meant.

2. Did the event match the trigger?

# The trigger block of a workflow: everything between on: and jobs:
sed -n '/^on:/,/^jobs:/p' .github/workflows/FILE.yml
# Real output from the test repository, as run (setups A and B printed the same): the filter names master, but the test branch is obf-lab or obf-test
on:
  push:
    branches: [master]
jobs:

The last line, jobs:, is the end of the range, so sed prints it too.

Each commit in the test repository was then checked for runs:

# Number of workflow runs for each of the last three commits on the test branch (setup A used origin/obf-lab; use your own branch; for a private repository use gh api repos/OWNER/REPO/actions/runs?head_sha=$sha --jq .total_count instead of curl)
git log -3 --format='%H %s' origin/obf-lab | while read sha msg; do echo "$(curl -s "https://api.github.com/repos/OWNER/REPO/actions/runs?head_sha=$sha" | jq .total_count) run(s): $msg"; done
# Real output from the test repository (setup A; setup B printed the same three lines)
0 run(s): Change app [skip ci]
1 run(s): Update docs only
2 run(s): Add test workflows
CommitWhat ranWhy
Add test workflows (adds src/app.py)runs-on-push, paths-filterbranch-filter wants master. manual only reacts to a manual start
Update docs onlyruns-on-pushpaths-filter has paths: ['src/**'], and only docs/ changed
Change app [skip ci]nothing[skip ci] in the commit message: no push workflow ran for that commit (pull_request was not tested)

What to check in the trigger:

  • Branch names: main vs master, and glob patterns (release/* does not match release/1.0/hotfix; release/** does).
  • Branches and tags together: if a push trigger sets only branches, pushing a tag runs nothing, and with only tags, branch pushes run nothing.
  • paths and paths-ignore: the files changed in the push must match. We tested a paths filter on push only; paths-ignore was not tested.
  • Skip words: [skip ci], [ci skip], [no ci], [skip actions] or [actions skip] in the commit message. In setup B, a plain control commit started 1 run and each of these five words in the subject gave 0 runs; [skip ci] written only in the commit body also gave 0. We tested single-commit pushes only, so we do not know what happens when the word is in a commit that is not the head of a multi-commit push.
  • The skip-checks: true trailer depended on the blank lines before it in our test (setup B, single empty commits on a push event). With one blank line between subject and trailer, the push started 1 run. With two real blank lines before the trailer, the push started 0 runs, and skip-checks:true without a space plus two blank lines also gave 0. We checked the stored message with git cat-file -p HEAD | sed 1,4d | cat -A and created the two-blank-line commits with git commit --cleanup=verbatim -F FILE. Git's default cleanup collapses two blank lines into one, so a commit made the normal way with two blank lines still had one and started a run. We did not test why the position matters, a trailer combined with a skip word, a body paragraph between subject and trailer, or the trailer on pull requests. Treat the five bracket words as the dependable way to skip a push.
  • The event itself: in setup B, a workflow with only on: pull_request ran 0 times on a plain push. After a pull request from the test branch into main was opened (not merged), it ran within 30 seconds, and its log showed ref refs/pull/1/merge, with a github.sha that differed from the head commit.
  • From the documentation, not tested: a required status check from a workflow skipped by a paths filter stays pending and can block a pull request.

3. Is the file on the branch the event reads?

Different events read the workflow file from different places.

EventWhich copy of the workflow file is used
pushThe pushed commit. A new workflow on a feature branch runs on that branch (tested)
pull_requestThe merge commit of the pull request, so the version from the pull request branch (documentation; in setup B the run used refs/pull/N/merge, a pull request with merge conflicts and forks were not tested)
workflow_dispatchThe branch you pick, but the Run workflow button only appears when the file is on the default branch (documentation; not tested, see the bullet below)
scheduleThe default branch only (documentation; see the bullet below)

Only the push row was fully tested; the other rows are from the GitHub documentation unless noted. What we saw in setup C (the private repository, a branch created for the test, Git 2.53.0, gh 2.46.0):

  • push: a new file with on: push and no branch filter, pushed only to the test branch, ran on that branch (obf-feature push obf-test completed/success). The repository's workflow for main did not run for that push.
  • workflow_dispatch: a file that exists only on the non-default branch was not in the registered-workflows list, and gh workflow run obf-dispatch.yml --ref obf-test and --ref main both returned HTTP 404: Not Found. We did not test the reverse (a dispatch file on the default branch run with a --ref of another branch) or the button in the web UI.
  • schedule: a file with cron: '*/5 * * * *' only on the non-default branch was not in the registered list, and the API showed 0 schedule runs in about 4 to 5 minutes. That is weak evidence: the window was short, and scheduled runs can be delayed.

For schedule, these rules are from the GitHub documentation and were not tested by us:

  • In a public repository, GitHub disables scheduled workflows after 60 days without activity in the repository. The state turns to disabled_inactivity.
  • Scheduled runs can start late or be dropped when GitHub is under heavy load, especially at the start of an hour. Pick an odd minute (17 3 * * *, not 0 3 * * *).
  • The cron expression is in UTC: 0 1 * * * is 03:00 in Sofia in summer and 02:00 in winter.

4. Did GitHub suppress the event?

These rules are from the GitHub documentation. They were not reproduced in our tests.

  • Events made with GITHUB_TOKEN do not start new runs. A workflow that pushes a commit or opens a pull request with the default token does not trigger push or pull_request workflows (except workflow_dispatch and repository_dispatch). Use a GitHub App token or a fine-grained token when a chain of workflows is intended.
  • Pull requests from forks: for first-time contributors, a maintainer must approve the run. Until then it waits, and secrets are never passed to fork runs on pull_request.
  • A pull request with merge conflicts does not run pull_request workflows until the conflict is resolved.
  • Actions or the workflow is disabled (section 1).

5. Verify

# After the fix: push one commit and confirm a run exists for it (public repository; for a private one use the gh api variant below)
git push origin BRANCH
curl -s "https://api.github.com/repos/OWNER/REPO/actions/runs?head_sha=$(git rev-parse HEAD)" | jq -r '.workflow_runs[] | "\(.name)  \(.event)  \(.status)"'
# Private repository: the same query through gh api (the curl command printed Not Found for a private repository in our test)
gh api repos/OWNER/REPO/actions/runs?head_sha=$(git rev-parse HEAD) | jq -r '.workflow_runs[] | "\(.name)  \(.event)  \(.status)"'
# Real output from the test repository (setup B): the gh api command right after the push, for HEAD and for HEAD~1
obf-runs-on-push  push  queued
obf-runs-on-push  push  completed

In one sample, polling the API every 0.5 seconds, the first run was visible 4.5 seconds after git push returned (the push itself took 1.6 seconds). The first answer showed it as queued; HEAD~1 was completed. One sample: GitHub can be slower under load. The curl form returned Not Found against the private repository; in setup A (public repository) we ran it against HEAD~1 and it printed runs-on-push push completed. The unauthenticated rate limit read from the API was 60 requests an hour.

6. Rollback and prevention

  • Rollback: a trigger change is a normal commit. In setup B we changed a trigger to branches: [master] (0 runs on the next push), ran git revert --no-edit COMMIT, and the next push started 1 run again. Revert it if the workflow now runs too often or on the wrong branch.
  • Add workflow_dispatch: to workflows you may need to start by hand. It costs nothing and gives you a test button.
  • Prefer conditions in jobs over paths filters for required checks, or add a small job that always reports, so pull requests are not blocked by a check that never starts.
  • Lint workflow files in review (for example with actionlint), so typos in event names and filters are caught before they silently do nothing.

What we have not verified

  • Section 3: a workflow_dispatch file on the default branch (and run with another --ref), the Run workflow button in the UI, and schedule beyond a window of about 4 to 5 minutes; the disabled_inactivity state and the 60-day rule, the odd-minute advice and the UTC claim.
  • Section 4: GITHUB_TOKEN suppression, fork-run approval and pull requests with merge conflicts.
  • Skip words: multi-commit pushes with a skip word in a commit that is not the head commit; skip-checks on pull requests; why the trailer position matters.
  • Filters: paths-ignore, tag filters, and glob patterns (release/* vs release/**). A required status check left pending by a skipped workflow (needs branch protection).
  • Settings and policy: Settings → Actions → General and the organization policy.
  • Section 6 advice: actionlint (not run), and "prefer conditions in jobs over paths filters".
  • The Enable workflow button (we used gh workflow enable), and the Actions tab left-hand list.
  • Timing: the section 5 timing is one sample. Merge-conflict pull requests and forks were not tested.

References

Official reference

docs.github.com ↗

Technical steps are original explanations; consult the upstream documentation for version-specific details.

Behavior differs by distribution and tool version. Commands are examples for authorized systems; review output for secrets before sharing.

Found this useful?

Follow us on YouTube for video explainers, and find us on Facebook to keep up with what is new.