Why didn't my job run? Ask GitHub's own parser.

Paste a GitHub Actions workflow, pick the event, and see which jobs run and why, down to the value of every sub-expression. The page bundles GitHub's own workflow parser and expression engine and runs them in your browser. Nothing is uploaded, there is no server and no key.

Published 2026-09-12 · updated 2026-09-18 · 95 tests · 74 real runs recorded; 757 job decisions and 60 trigger decisions replayed · about 600 KB, static

The problem

Every GitHub Actions user has stared at a grey "skipped" job and asked why. The usual way to find out is a dozen "test ci" commits, each one a minute of waiting, each one changing one thing in an if: line until the job goes green. The expression language has coercion rules that are easy to get wrong, the on: filters have their own pattern syntax, and a skipped job silently skips everything that needs it.

This page answers in a second. Paste the workflow, choose push to main or a pull_request from a fork with a release label or a workflow_dispatch with deploy: true, and read the answer.

if: github.event.pull_request.head.repo.fork == false
→ SKIPPED on pull_request from a fork:
  github.event.pull_request.head.repo.fork is true → ... == false is false
→ RUNS on push (probably not what you meant):
  github.event.pull_request.head.repo.fork is null → null == false is true
  (loose equality: null and boolean are compared as numbers, null/false/'' count as 0)

What it does

• Trigger decision. Does this event start the workflow at all? The on: filters are applied in the documented order: activity types (and the pull_request default of opened, synchronize, reopened), branches and branches-ignore, tags, paths and paths-ignore, with GitHub's pattern syntax. Each rule reports what it matched.
• Job decisions in dependency order. Every job's if: is evaluated by GitHub's own expression package, including the implicit success() && wrapper its parser adds to a condition that has no status function, with needs.<job>.result and the status functions computed from every job upstream: the recorded runs show success() and failure() look at all ancestors, not only the direct needs. Mark a job as failed or cancelled to see what failure(), always() and !cancelled() do downstream.
• Why. The decisive comparison is named with both sides' values, and a note explains the coercion: null == false is true, inputs.deploy == 'true' is false for a boolean input, string comparison is case-insensitive. Expand a job to see every sub-expression and its value.
• Matrix expansion. A job with strategy.matrix becomes the jobs GitHub creates for it, each under the name the run lists (test (linux, 20)), with its own matrix values and its own step decisions: the cross product, exclude, include (added to the combinations it fits, or a combination of its own), fail-fast (mark one combination as failing and the others are cancelled with GitHub's annotation) and the result the jobs that need it see. A matrix read from a job output (fromJSON(needs.plan.outputs.list)) stays unknown until you type that output. When it comes out empty, the card says what GitHub does and does not tell you, below.
• Things GitHub rejects. A job-level hashFiles(), matrix or secrets in a job if:, branches together with branches-ignore, an unknown key: the file is reported as GitHub would reject it and every job is marked not run, as the recorded runs show: a failed run named after the file, with no jobs, sibling jobs included. A filter list with only negative patterns is different: GitHub creates no run at all, and the trigger card says so.
• The context you get. The github context for the scenario, derived per event as documented, with the GitHub Docs description of every field on hover.
• Share. One link carries the workflow and the scenario, compressed into the URL fragment.

On the command line

On the page you tell the simulator which files changed. Inside your repository git already knows, so the command line version reads the workflows, the branch, the commit and the changed files from the repository you run it in, and prints what the page would show for every workflow and every job. It needs Node 22 or later and git.

cd your-repository
npx github:barbarkaragul-oss/why-didnt-my-job-run                        # a push of the last commit on this branch
npx github:barbarkaragul-oss/why-didnt-my-job-run --event pull_request   # this branch as a pull request into the default branch

What comes from git: the workflows from .github/workflows in the working tree, uncommitted edits included, so a change can be tried before it is pushed. For a push, the changed files are git diff --name-only <base>..<head>, the base defaulting to the head's first parent (a push of one commit; --base origin/main for a push of several). For a pull request, they are the diff from the merge base of the base branch and the head, which is the diff GitHub matches paths against. The repository comes from the origin remote and the default branch from origin/HEAD. Everything else takes the page's defaults, and flags such as --label, --input, --output and --fail set what git cannot know. Each job is printed as runs, skipped, fails, cancelled, blocked, rejected or not-created, a matrix job with one line per job GitHub creates, and --json prints all of it for scripts.

--expect-run turns a question into an exit code: 1 unless the named job (or matrix combination) runs. As a check in CI, for example to make sure a change to the workflow keeps deploy running on pushes to main:

- uses: actions/checkout@v7
  with:
    fetch-depth: 0   # the diff needs the commit before the head
- run: npx --yes github:barbarkaragul-oss/why-didnt-my-job-run --branch main --expect-run deploy

npx downloads the repository and runs dist/cli.js, one committed file with GitHub's parser packages bundled in; nothing else is installed and nothing is built on your machine. The package is not on the npm registry; to pin a version, add a commit: npx github:barbarkaragul-oss/why-didnt-my-job-run#<sha>.

How it works

GitHub publishes the pieces of its Actions language server as MIT-licensed npm packages, the same ones its VS Code extension uses to validate workflows:

• @actions/workflow-parser parses the YAML against the real workflow schema and fills in the documented defaults: a job without if: gets success(), a job with if: x gets success() && (x), invalid keys are errors.
• @actions/expressions is the ${{ }} engine: lexer, parser, evaluator, coercion rules, contains, startsWith, format, fromJSON, object filters.

Both are pure JavaScript with no Node dependencies, so the page bundles them and runs them in the browser. What is written for this project is only what the packages do not cover:

The example payloads come from GitHub's @octokit/webhooks-examples; the scenario knobs patch them.

Verified against real runs

Documentation can be read two ways; a run cannot. The fixtures repository, barbarkaragul-oss/wdmjr-fixtures (public, every run visible under its Actions tab), ran a workflow with 31 deliberately tricky jobs (32 rows as GitHub lists them, since the matrix job has two legs: fork checks, label checks, null == false, inputs.deploy == 'true', needs chains with a failing build, always(), !cancelled(), needs.x.result == 'skipped', github.run_attempt == 1, case-insensitive ref_name == 'MAIN', a job-level hashFiles()) on real pushes to branches and tags, pull requests (opened, labeled, draft), two manual dispatches, a release and a labelled issue. Each run dumped its own toJSON(github); the API reported each job's conclusion. Two more workflows chained jobs three deep behind a failing job and behind a job skipped by its own condition, one tested step-level conditions, and one more, dispatched by hand, pinned down matrices. The simulator's repository holds 74 recordings (22 of the 31-job workflow with its full github context, the chain and step workflows, six filter workflows, 16 failed runs of rejected files, and the matrix workflow), and the replay tests require the simulator to reproduce 757 job run-or-skip decisions and 60 trigger decisions, plus every job of the matrix run under its full name. npm test runs them.

When the matrix comes out empty

A common way to run one job per changed package is to let an earlier job write the list and build the matrix from it with fromJSON(). The matrix workflow in the fixtures repository recorded what GitHub does when that list comes out empty, as it does when nothing changed. The workflow, trimmed to the lines that matter:

plan:
  outputs:
    whole_empty: ${{ steps.p.outputs.whole_empty }}
  steps:
    - id: p
      run: echo 'whole_empty={"include":[]}' >> "$GITHUB_OUTPUT"
whole_json_empty:
  needs: plan
  strategy:
    matrix: ${{ fromJSON(needs.plan.outputs.whole_empty) }}
after_whole_json_empty:
  needs: whole_json_empty
after_whole_json_empty_always:
  needs: whole_json_empty
  if: always()

A single key read from an empty list (target: ${{ fromJSON(needs.plan.outputs.none) }} with none=[]) ended the same way. So a run can finish with a job that is simply not there, and the only trace is downstream: the jobs that need it see failure and, unless they use always(), are skipped. The simulator keeps a matrix read from a job output unknown until you type that output; type an empty one and the card says what GitHub does and does not tell you, and the command line version prints the job as not-created.

The same run pinned down the rest of matrix expansion. An include entry is added to every combination whose original values it does not contradict, and an entry that fits none becomes a job of its own. The job name lists the values of the original keys only, in the order they are declared (include_exclude (apple, cat), although that job also has a color and a shape). With fail-fast, the default, one failing combination cancelled the others with the annotation The strategy configuration was canceled because "failfast._2" failed.; without it they finished; either way the jobs that needed the matrix saw failure. And a matrix job whose own if: is false is one skipped job under its plain name, not one per combination.

Limits

• On the page, changed files are typed by you, for the reason above. The command line version reads them from git.
• Matrices are expanded as GitHub's parser expands them and as the recorded run confirms, with two things left to you. Job outputs are whatever you type: a matrix that reads one stays unknown until you do, because only the job knows what it writes. And a run is not a timeline: max-parallel is shown but changes no outcome, and when one combination fails with fail-fast on, every other combination is taken to be still running and cancelled (on GitHub, those that already finished keep their result). Two cases are assumed to end like the recorded empty matrix, and the card says so: an exclude that removes every combination, and a strategy GitHub cannot build, such as a job output used without fromJSON().
• Reusable workflow jobs are decided but not expanded.
• Step conditions are evaluated with the job's own step status and every previous step assumed to have succeeded (the recorded runs confirm step-level success()/failure() look at the job's steps, not at needs); a step whose condition reads steps.<id>.*, env or hashFiles() is marked unknown rather than guessed. A condition that reads matrix is decided for each combination.
• Not simulated: concurrency groups, required checks, environment protection rules, workflow_run chains, timeouts.

Wrong result? Open an issue with the workflow and the event. If a real run disagrees with the simulator, that run becomes a fixture.

How it was built

The first version was written in one day with Claude Fable 5.1 doing the typing and a human deciding what to build, what to verify and what to ship. The reason that is acceptable for a tool people will trust with their CI is the ground-truth harness: the fixtures repository, the recorded contexts and the replay tests are what make the answer right, not the model. When the simulator and GitHub disagree, GitHub wins and the run becomes a test.

Run it locally

git clone https://github.com/barbarkaragul-oss/why-didnt-my-job-run && cd why-didnt-my-job-run
npm install
npm test          # docs-derived filter tests + ground-truth replay + the CLI against temporary git repositories
npm run bundle    # docs/ (the static site) and dist/cli.js (the command line version); both are committed
npx tsx src/cli.ts --help   # the command line version straight from the source

• Simulator: barbarkaragul-oss.github.io/why-didnt-my-job-run
• Repository: github.com/barbarkaragul-oss/why-didnt-my-job-run (MIT)
• Sister projects: AgentMatrix and PrivacyMatrix, cited comparison matrices