Skip to content

feat: find the GitHub Actions workflows that can never run - #1

Merged
jennifer-barber[bot] merged 6 commits into
mainfrom
shift/2026-09-09-deadtrigger
Sep 9, 2026
Merged

jennifer-barber[bot] merged 6 commits into
mainfrom
shift/2026-09-09-deadtrigger

Conversation

@richmond-avenal

Copy link
Copy Markdown
Contributor

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 to deadowners in 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:

python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest          # 176 tests

Then run the README's "A real example" block verbatim — copy the whole bash block 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:

git clone --filter=blob:none https://github.com/astral-sh/ruff
deadtrigger ruff

Three findings in .github/workflows/typing_conformance.yaml. crates/ruff_db, crates/ruff_python_ast and crates/ruff_python_parser are directories; path filters only ever match the paths of changed files; the neighbouring lines in the same list are written crates/ty*/** and crates/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_db shows it is a tree, not a blob.

Breaking it, in the demo repo from the README:

deadtrigger --ref no-such-revision   # exit 2
deadtrigger /tmp                     # exit 2, not a git repository
deadtrigger --json                   # same findings, machine-readable

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 --ref is exit 2, and fails if any check declines to run in a full clone.

What I'm unsure about

1. impossible-if decides 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 on github.event_name == 'schedule' in a workflow whose schedule: 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. paths filters can be legitimately forward-looking, and I report them anyway. paths: ['terraform/**'] in a repo about to grow a terraform/ is a false positive by any reasonable reading. I went the other way for branch filters — only wildcard-free patterns are reported there, because release/** 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_run matching an unnamed workflow. GitHub matches workflows: [X] against the other workflow's name:. When a workflow has no name:, GitHub displays its file path — but the docs never say whether workflow_run will 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 * , - /, plus JAN–DEC, SUN–SAT and 7 for 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 false dead-cron, which is the wrong direction. @daily is the case I'm most confident about (GitHub does not take the nicknames); 5/10 is the one I'm least sure of, and I chose to accept it.

What's deliberately not done

  • Step-level if:. Job level only. Steps would multiply the output for the same weak check.
  • github.event.pull_request on a workflow with no PR trigger. Looks like it belongs here; it's a trap. The value is null, and in GitHub's expression language null == false compares 0 to 0 and is true, so the obvious reading of a draft check comes out backwards. Documented in ifexpr.py and in the README so the next person doesn't "fix" it.
  • The five-minute cron floor. GitHub runs those less often, not never — out of scope for a tool about things that never fire.
  • Whether a workflow_call workflow has any caller. It can be called from another repository, and this only ever looks at one.
  • --explain. deadowners has it; there wasn't room tonight, and the detail field already carries most of what it would say.
  • No release tag. That's yours.

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? are page.js and page.jsx and not page.jsz. Anything built on fnmatch is 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 on is a boolean. yaml.safe_load returns True as 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.py asserts 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, 5 workflow_run references, 198 job conditions. Three findings, all in ruff, 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 greenwash result.

Housekeeping

Branch protection was applied to main before 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

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.
@richmond-avenal

Copy link
Copy Markdown
Contributor Author

One change since the description above, worth flagging because the dogfood job found it rather than me.

fix: check workflow files that are not in git yet (13d0326). The dogfood step writes a workflow with a dead path filter and asserts exit 1. It got 1 workflow checked, clean instead. Candidate workflow files were being taken from the git index, so a file nobody had git added was never examined — and produced no findings and no warning, which reads exactly like a clean workflow. That is the failure this whole tool is about, in the tool.

Workflow files now come from the .github/workflows directory when no --ref is given. What they're checked against still comes from git, deliberately: path filters match the paths of changed files, and an untracked build/ directory is not something anyone can change in a commit. There's a test for each half of that (test_a_workflow_file_that_is_not_in_git_yet_is_still_checked, test_untracked_files_are_not_counted_as_matches).

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.

@jennifer-barber jennifer-barber Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. impossible-if at 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.
  2. 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; a paths: 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.
  3. workflow_run accepting 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.

@jennifer-barber
jennifer-barber Bot merged commit fd6723a into main Sep 9, 2026
3 checks passed
@jennifer-barber
jennifer-barber Bot deleted the shift/2026-09-09-deadtrigger branch September 9, 2026 12:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants