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.
On this page
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 workflowsA 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.
0. Rules of engagement
- Change one thing per test commit. Trigger rules combine, and two changes at once make the result impossible to read.
- Read before you edit. Sections 1 to 3 only look at files and at what GitHub registered.
- Do not add
on: pusheverywhere 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 activesingular.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: 3An 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 34The 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| Commit | What ran | Why |
|---|---|---|
Add test workflows (adds src/app.py) | runs-on-push, paths-filter | branch-filter wants master. manual only reacts to a manual start |
Update docs only | runs-on-push | paths-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:
mainvsmaster, and glob patterns (release/*does not matchrelease/1.0/hotfix;release/**does). - Branches and tags together: if a push trigger sets only
branches, pushing a tag runs nothing, and with onlytags, branch pushes run nothing. pathsandpaths-ignore: the files changed in the push must match. We tested apathsfilter onpushonly;paths-ignorewas 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: truetrailer 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, andskip-checks:truewithout a space plus two blank lines also gave 0. We checked the stored message withgit cat-file -p HEAD | sed 1,4d | cat -Aand created the two-blank-line commits withgit 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_requestran 0 times on a plain push. After a pull request from the test branch intomainwas opened (not merged), it ran within 30 seconds, and its log showedref refs/pull/1/merge, with agithub.shathat differed from the head commit. - From the documentation, not tested: a required status check from a workflow skipped by a
pathsfilter 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.
| Event | Which copy of the workflow file is used |
|---|---|
push | The pushed commit. A new workflow on a feature branch runs on that branch (tested) |
pull_request | The 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_dispatch | The 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) |
schedule | The 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 withon: pushand no branch filter, pushed only to the test branch, ran on that branch (obf-feature push obf-test completed/success). The repository's workflow formaindid not run for that push.workflow_dispatch: a file that exists only on the non-default branch was not in the registered-workflows list, andgh workflow run obf-dispatch.yml --ref obf-testand--ref mainboth returnedHTTP 404: Not Found. We did not test the reverse (a dispatch file on the default branch run with a--refof another branch) or the button in the web UI.schedule: a file withcron: '*/5 * * * *'only on the non-default branch was not in the registered list, and the API showed 0scheduleruns 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 * * *, not0 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_TOKENdo not start new runs. A workflow that pushes a commit or opens a pull request with the default token does not triggerpushorpull_requestworkflows (exceptworkflow_dispatchandrepository_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_requestworkflows 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 completedIn 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), rangit 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
pathsfilters 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_dispatchfile on the default branch (and run with another--ref), the Run workflow button in the UI, andschedulebeyond a window of about 4 to 5 minutes; thedisabled_inactivitystate and the 60-day rule, the odd-minute advice and the UTC claim. - Section 4:
GITHUB_TOKENsuppression, 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-checkson pull requests; why the trailer position matters. - Filters:
paths-ignore, tag filters, and glob patterns (release/*vsrelease/**). 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 overpathsfilters". - 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
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.