| name | github-run-failure |
| description | Use to analyze failures in GitHub pipelines or jobs. |
- Assume the `gh` tool is installed and configured.
- Avoid printing full logs; focus on the failing step.
- For large logs, prefer downloading artifacts.
- If a test case failed, specify which test and how to run it locally.
List recent runs
gh run list --limit 20 --json databaseId,createdAt,headBranch,event,conclusion,status,displayTitle \
--template '{{range .}}{{printf "%8v %-20s %-8s %-10s %-10s %s\n" .databaseId .createdAt .status .conclusion .event .displayTitle}}{{end}}'
Inspect a single run
RUN_ID=123456789
gh run view "$RUN_ID" --json status,conclusion,createdAt,headSha,headBranch,event,workflowName,url
Show only failed jobs or steps
gh run view "$RUN_ID" --json jobs --jq '
.jobs[]
| select(.conclusion != "success")
| .name as $job
| (.steps[]? | select(.conclusion != "success") | "\($job) :: \(.name) :: \(.conclusion)")'
View failed jobs/steps output
gh run view "$RUN_ID" --log-failed
To focus on a specific job, first list them:
gh run view "$RUN_ID" --json jobs --jq '.jobs[] | "(.databaseId)\t(.name)\t(.conclusion)"'
Then fetch that job's log:
JOB_ID=987654321
gh run view "$RUN_ID" --job "$JOB_ID" --log
List artifacts from a run
gh run download "$RUN_ID" --list
Download a specific artifact
gh run download "$RUN_ID" --name "test-logs" --dir /tmp/github-run-"$RUN_ID"
After downloading, search locally for errors:
rg -n "error|fail|exception" /tmp/github-run-"$RUN_ID"
Compare failed and latest successful run
Get latest successful run ID:
BRANCH=main
OK=$(gh run list --branch "$BRANCH" --limit 50 --json databaseId,conclusion
--jq '.[] | select(.conclusion=="success") | .databaseId' | head -n1)
echo "$OK"
Diff their SHAs:
FAIL_SHA=$(gh run view "$RUN_ID" --json headSha --jq .headSha)
OK_SHA=$(gh run view "$OK" --json headSha --jq .headSha)
gh api repos/:owner/:repo/compare/"$OK_SHA"..."$FAIL_SHA" --jq '.commits[].commit.message' | sed 's/^/- /'