GitHub Actions failure triage: an ordered checklist of what to check first

What this tool does, and what it does not

You answer up to eight questions about one failing run: which stage fails, since when, whether the same command passes on your machine, what a re-run of the same commit did, where it fails, which runners fail, what changed recently and what the job relies on. Only the stage is required. The tool then lists the checks worth doing, in an order it can explain, each with the reason for the check, the evidence to collect and a note on what that check cannot tell you.

It is not an automated diagnosis. Nothing reads your logs, repository, workflow file or runners, and the list does not rank causes by likelihood. It says what is cheapest and most informative to check first, given only your answers.

• Answers are used only to choose and order checks; they are not sent anywhere or stored.
• Do not paste logs, secrets or customer data into any field: there is no free-text field on purpose.
• An item you cannot confirm is not ruled out, and a failure can have more than one cause.

How the order is decided

The whole logic is two tables in the tool's script, shown on the page under 'How this list was built' and exercised by its tests. The rule table says when each check is listed and gives it an order number inside one of four groups: establish the facts, compare what passed with what failed, check the likely cause for your stage and changes, and decide what happens next. Items are sorted by group, then by order number (lower first), then by rule id.

A promotion table lowers the order number of a check inside its own group when a stated condition holds. Promotions never move a check into an earlier group. For example, if a re-run of the same commit passed, the check for a pattern across pass and fail history moves ahead of the local-versus-CI comparison, because a green re-run of the same commit is direct evidence that the result is not repeatable. If you named a change in dependencies, an action version, the workflow file or a tool version, the check for that change moves ahead of the checks that apply to the failing stage in general.

• Group 1 asks for facts that cost minutes: the first error line, a same-commit re-run, the last green run, which commit was actually tested.
• Group 2 compares environments: your machine, forks, push versus pull request, runner image, one matrix combination, a self-hosted runner.
• Group 3 checks causes tied to your stage and to the changes and dependencies you named.
• Group 4 always ends with a written hand-off decision, and adds an ownership check if the failure recurs.

If the matrix is wider than the box, scroll horizontally to read every column. Keyboard: focus the matrix and use Left/Right.

Worked example (from the tool's test suite, not a customer case; item titles shortened)
Answers: stage = unit tests; passes locally; re-run of the same commit passed; fails now and then

 1. R01  group 1  Read the first error, not the last one
 2. R04  group 1  Confirm which trigger and which commit the job tested
 3. R11  group 2  Collect the pass and fail history (order 20, promoted to 5 by P1)
 4. R10  group 2  Compare your machine with the CI job, item by item
 5. R30  group 3  Isolate the failing test and run it alone, then in order
 6. R90  group 4  Write down what you found, and decide who owns the next step
 7. R91  group 4  If this keeps recurring, treat it as a standing responsibility

What the questions are for

Each answer switches specific rules on or moves them. 'Same command passes locally' switches on the comparison of your machine with the CI job and the check of which commit was tested. 'Only on pull requests from forks' switches on the fork check and replaces the general secrets check, because GitHub does not pass secrets to workflows triggered from a forked repository (GITHUB_TOKEN excepted) and makes GITHUB_TOKEN read-only there. 'Re-run passed' or 'fails now and then' switches on the history check and the ownership check. 'Not re-run yet' adds the same-commit re-run as an early step, because GitHub's re-run uses the same commit SHA and ref as the original. It is left out when the job never started, because there is no failed job to re-run, and for a failing deploy or release step it comes with a warning to re-run only if that step is safe to repeat. 'It used to pass and I cannot name a change' switches on the runner-image check and the external-service check (if the job calls one) and moves them earlier, because with no change in your repository those are the places left to look.

• A pull_request run tests the merge commit of the pull request, not the branch tip, and does not run at all while the pull request has a merge conflict.
• A '-latest' runner label points at an image version GitHub chooses and moves over time, so the image can change without a commit.
• A re-run repeats whatever the job does, so a failed deploy or release step is re-run only if it is safe to repeat: a publish, a migration or a notification can happen twice.
• An unset secret evaluates to an empty string instead of failing loudly, which is why 'check the secret exists, never print it' is a listed step.

What this cannot tell you

It cannot tell you why the job failed. It cannot see your logs, your workflow file, your runners, your secrets or the services you call, and it cannot know that two causes are interacting. The rules are general GitHub Actions practice, not knowledge of your repository, and a rule that does not fire may still describe your problem.

Where a step depends on something only its owner can see, such as a self-hosted runner, a cloud trust policy or an external provider's status, the item says so in its own 'what this cannot tell you' note.

• Retrying a job or quarantining a test hides a failure; it does not fix it.
• Giving secrets to workflows from forks is a security decision, not a CI fix.
• If the same job keeps failing, the one-off fix and the ongoing responsibility are different jobs; the page links both.

Handing the failing job over

If you would rather have the job fixed than investigate it yourself, the one-off outcome is to fix a single failing GitHub Actions job and show a green run on the same trigger, with before-and-after logs. If the same workflows keep going red, the continuing version is to keep your GitHub Actions CI green month after month. Both are described, with scope, required inputs and what is not included, on their own pages. This tool is free and does not require either.