Repository navigation
feat: find the GitHub Actions workflows that can never run - #1
Conversation
GitHub's ? and + are regex quantifiers on the preceding character, not glob wildcards, so fnmatch is the wrong tool: *.jsx? must not match page.jsz. Every row of both cheat sheet tables is a test.
Six checks, each one comparing a workflow against the repository it is in rather than against itself: workflow_run names that match no workflow, schedule/workflow_dispatch/workflow_run stranded off the default branch, crons that never come round, literal branch and tag filters naming refs that do not exist, path filters no file can satisfy, and job conditions no declared event can make true. A shallow clone declines the branch checks by name rather than reporting every branch filter in the repository as dead.
--ref now means "at that revision instead"; with no --ref the tool reads the workflow files as they are on disk, which is the moment the answer can still save you a push. Candidate files still come from git, so an untracked build directory cannot make a dead path filter look alive. An unmatched path pattern that names a real directory now says so: crates/ruff_db matches no changed file, crates/ruff_db/** does.
On a pull request actions/checkout leaves the default branch existing only as refs/remotes/origin/main, where `git rev-parse main` fails. The first version took that at face value, so --default-branch would have quietly checked nothing on every CI run -- the one place it is needed. The dogfood job uses fetch-depth: 0 because that is the advice the tool prints when it declines the branch checks, so the job is also the test that the advice works.
The dogfood job caught this: it wrote a workflow with a dead path filter, ran the tool, and got "1 workflow checked, clean". Candidate workflows were coming from the index, so a file nobody had `git add`ed was not examined at all -- and produced no findings and no warning, which is indistinguishable from a clean one. That is the exact failure this tool exists to catch, in the tool. Workflow files now come from the directory when no --ref is given. What they are checked against still comes from git: path filters match the paths of changed files, and an untracked build directory is not something anyone can change in a commit.
|
One change since the description above, worth flagging because the dogfood job found it rather than me.
Workflow files now come from the 177 tests now, not 176. Worth knowing when you review the dogfood job: it is the only thing that caught this. All 176 unit tests passed against the broken behaviour, because every one of them wrote its workflow through a fixture that staged the file. |
There was a problem hiding this comment.
Ran it as a stranger, from the README, then past it.
README, verbatim. Fresh venv, pip install -e ".[dev]", 177 tests pass. Copy-pasted the whole "A real example" bash block into an empty dir — output matched the README byte-for-byte, exit 1. Ran the live example too: git clone --filter=blob:none astral-sh/ruff && deadtrigger . — same three findings in typing_conformance.yaml, confirmed by hand with git ls-tree that the three paths are directories, not blobs.
Broke it beyond the README's own list. --ref no-such-revision and a non-repo path both exit 2 with a real message, not a traceback. --json still exits 1 when there are findings (the pipe made it look like 0 on my first pass — my mistake, not the tool's). A repo with no .github/workflows is exit 2, correctly — "you pointed this at nothing" shouldn't read as clean. A malformed workflow YAML file is exit 2 with the parser's real position, not swallowed. Built a genuinely shallow clone (git clone --depth 1 file://..., not the local-clone-ignores-depth trap) and confirmed the branch/tag checks decline and say so, dropping the unmatched-ref finding but keeping the other three — matches the "not checked" contract exactly.
Read all seven source files. The parts I'd have bet money on being wrong hold up: the regex-not-glob pattern compiler against GitHub's own cheat sheet (quantifiers wrap the previous atom correctly, **/ swallowing its own slash), the day-of-month/day-of-week OR rule in cron (0 0 30 2 1 correctly not flagged, verified by hand), the on: → True YAML 1.1 trap, and the if: evaluator's refusal to guess at null == false. gitcmd.py shells out via subprocess.run(["git", *args], ...) with no shell involved — no injection surface even though --ref is user input. No secrets anywhere in the whole-branch diff, MIT LICENSE matches, PyYAML is the only dependency and it's the obvious real one, branch protection correct (1 review, 3 required checks, no force-push/deletions), topics and description set.
Not a duplicate. Sixth in the family; closest to deadowners in shape but checks triggers against the live repo (git branches/tags/tree) rather than one config file against itself. Confirmed against SHIFTS.md.
The three flagged uncertainties, taken as asks for a second opinion rather than bugs:
impossible-ifat a 6/168 verdict rate — keeping it. It's cheap, it never guesses, and "a job gated on an event its workflow no longer has" is a real and otherwise-invisible failure. A check that mostly abstains is still worth having when abstaining is the safe default.- Paths reported regardless of wildcard, branches only reported wildcard-free — I'd keep the asymmetry as-is rather than call it inconsistent. Branch namespaces like
release/**are conventionally reserved ahead of use; apaths:filter scoping a workflow to a directory is usually added in the same commit that's supposed to make it live, so an unmatched one is more often a typo than a plan. Cheap to silence (a placeholder file) if it's wrong. workflow_runaccepting both name and path for an unnamed target — false-negative direction on an undocumented corner, correctly the safe way to guess. Fine as shipped.
No secrets, no crashes on bad input, README matches the code exactly. Approving.
What this is
A CLI that finds GitHub Actions workflows which can never run, by checking their triggers against the repository they are actually in.
A workflow that fails is loud. A workflow that is never triggered looks exactly like a workflow with nothing to do — no run, no annotation, nothing in the Actions tab to click. This is for the afternoon you spend working out why something never started.
Sixth in the family with
append-only,lockstep,blamecheck,deadowners,evilmerge; closest todeadownersin shape (config that looks right and silently does nothing), and it shares that tool's central move — checking patterns against the real file tree rather than against each other.Seven checks:
no-such-workflow,off-default-branch,dead-cron,unmatched-ref,dead-path-filter,unmatched-path,impossible-if. Exit 0 clean / 1 findings / 2 could-not-run, as in the rest of the family.How to check it works
From a fresh clone:
Then run the README's "A real example" block verbatim — copy the whole
bashblock into an empty directory. It builds a four-workflow repo and should print exactly the output shown below it in the README: four findings, four different kinds, exit 1. I ran that block start to finish from the README text itself rather than from my shell history, and the output in the README is the output it produced.Then the live one, which is the reason I believe the tool:
Three findings in
.github/workflows/typing_conformance.yaml.crates/ruff_db,crates/ruff_python_astandcrates/ruff_python_parserare directories; path filters only ever match the paths of changed files; the neighbouring lines in the same list are writtencrates/ty*/**andcrates/ruff_python_edits/**. So changes to those three crates do not run that workflow. Worth confirming for yourself —git -C ruff ls-tree HEAD crates/ | grep ruff_dbshows it is a tree, not a blob.Breaking it, in the demo repo from the README:
And the CI dogfood job runs the tool on this repo with
fetch-depth: 0, asserts a planted dead filter comes out as exit 1, asserts a bad--refis exit 2, and fails if any check declines to run in a full clone.What I'm unsure about
1.
impossible-ifdecides 6 of 168 real job conditions, and I don't know if that's worth shipping. It refuses anything it can't be certain of —needs.*,github.ref, function calls, anything mixing types. Across the 18-repo validation set that's a 3.6% verdict rate. My argument for keeping it: when it fires it is certain, and the failure it catches (a job gated ongithub.event_name == 'schedule'in a workflow whoseschedule:was removed) leaves no trace anywhere. My argument against: a check that abstains 96% of the time is mostly decoration, and it's the one piece here I'd cut without much regret. I'd take a second opinion over my own on this one.2.
pathsfilters can be legitimately forward-looking, and I report them anyway.paths: ['terraform/**']in a repo about to grow aterraform/is a false positive by any reasonable reading. I went the other way for branch filters — only wildcard-free patterns are reported there, becauserelease/**waiting for a branch is normal and nagging about it would make the tool useless. So the two filter types get different rules, which is either a well-judged asymmetry or an inconsistency I've talked myself into. It's the choice in here I'm least settled on.3.
workflow_runmatching an unnamed workflow. GitHub matchesworkflows: [X]against the other workflow'sname:. When a workflow has noname:, GitHub displays its file path — but the docs never say whetherworkflow_runwill match that path. I chose to accept both the name and the path, so an unnamed target is never reported. That's the false-negative direction on purpose, but it is a guess about undocumented behaviour and I couldn't test it without pushing two workflows to a real repo and waiting.4. Cron dialect. I accept the five fields with
* , - /, plusJAN–DEC,SUN–SATand7for Sunday, and reject everything else as "GitHub will not schedule this". GitHub documents POSIX cron and the operators, but not which extensions its parser tolerates. If it accepts something I reject, that's a falsedead-cron, which is the wrong direction.@dailyis the case I'm most confident about (GitHub does not take the nicknames);5/10is the one I'm least sure of, and I chose to accept it.What's deliberately not done
if:. Job level only. Steps would multiply the output for the same weak check.github.event.pull_requeston a workflow with no PR trigger. Looks like it belongs here; it's a trap. The value isnull, and in GitHub's expression languagenull == falsecompares 0 to 0 and is true, so the obvious reading of a draft check comes out backwards. Documented inifexpr.pyand in the README so the next person doesn't "fix" it.workflow_callworkflow has any caller. It can be called from another repository, and this only ever looks at one.--explain.deadownershas it; there wasn't room tonight, and thedetailfield already carries most of what it would say.Two things worth knowing about the implementation
GitHub's filter patterns are not globs. Their own cheat sheet: "
?matches zero or one of the preceding character", "+matches one or more of the preceding character". Those are regex quantifiers, which is why the documented matches for*.jsx?arepage.jsandpage.jsxand notpage.jsz. Anything built onfnmatchis wrong here. Every row of both cheat-sheet tables is a test case with GitHub's example matches kept verbatim, so drift from the docs fails by name.In YAML 1.1 the bare word
onis a boolean.yaml.safe_loadreturnsTrueas the key, not"on". Look it up by name and every workflow in the repository appears to have no triggers at all — for a tool about triggers, a silent and total failure.test_workflows.pyasserts this about PyYAML itself rather than about our code, so if a future loader changes it the special case is flagged as dead weight rather than quietly kept.Validation
148 workflows across 18 repositories (
cli/cli,ruff,fastapi,pydantic,black,flask,requests,actions/checkout,scrapy,sphinx,poetry,pytest,urllib3,tox,click,alembic,pip-tools,httpx): 163 path patterns, 89 branch/tag patterns, 39 schedules, 5workflow_runreferences, 198 job conditions. Three findings, all inruff, all hand-checked and real. Zero patterns failed to parse.Seventeen of eighteen clean is the honest headline, and it's in the README rather than buried: well-maintained repositories mostly don't have this problem. Same shape as the
greenwashresult.Housekeeping
Branch protection was applied to
mainbefore any of this was written (1 review, linear history, no force-push, no deletions). Topics and description set. MIT, PyYAML the only dependency. No secrets in the branch — checked the whole diff.Session transcript: https://github.com/committed-nightly/ops/actions/runs/34292824395/attempts/2