| name | github-action-failure-investigation |
| description | Guidelines for fetching, downloading, and analyzing failed GitHub Actions runs, including raw logs, packet captures, and detecting runner freezes. |
GitHub Action Failure Investigation
This skill provides step-by-step guidelines to retrieve and analyze failed
GitHub Actions runs, check job logs and packet capture artifacts, and classify
failure causes (real bugs vs. racy/frozen runners).
1. Prerequisites
Make sure you can run the GitHub CLI (gh) and are authenticated:
gh auth status
Note: If running inside a sandboxed environment that injects dummy tokens
(causing HTTP 401 errors), you may need to prefix commands with
env -u GITHUB_TOKEN to force gh to fall back to your normal credentials.
2. Fetching Job Metadata and Logs
Always create a dedicated staging directory to store logs and artifacts to avoid
cluttering the out/ root or dirtying the code source tree:
mkdir -p out/gha/<run_id>/
List Run Status and Artifacts
Use the Run ID from the URL (e.g.,
https://github.com/project-chip/connectedhomeip/actions/runs/<run_id>) to
check status and see available artifacts:
gh run view <run_id>
Download Raw Job Logs
If the run has completed, download the logs for a specific job:
gh run view <run_id> --job <job_id> --log > out/gha/<run_id>/job_logs.log
If the run is still in progress (but the specific job has completed), download
the logs via the GitHub REST API directly:
gh api repos/project-chip/connectedhomeip/actions/jobs/<job_id>/logs > out/gha/<run_id>/job_logs.log
