github-actions-inspection

# GitHub Actions Inspection ## When to Use This Skill | Use this skill when... | Use the linked sibling instead when... | |---|---| | Pulling status, logs, and conclusions from `gh run` for a failing workflow | Authoring or modifying a workflow YAML file — see claude-code-github-workflows | | Diagnosing flaky tests, timeouts, or auth-permission errors in a CI run | Searching upstream OSS issues for a library bug — see github-issue-search | | Rerunning failed jobs or extracting error lines from a completed run | Use `git-plugin:gh-workflow-monitoring` to block until an in-progress run finishes, or `git-plugin:git-fix-pr` to patch and push the fix | Expert knowledge for inspecting, debugging, and troubleshooting GitHub Actions workflow runs using gh CLI and GitHub API. For detailed examples, advanced patterns, and best practices, see [REFERENCE.md](REFERENCE.md). ## Core Expertise **Workflow Run Inspection** - Check workflow run status and conclusions - List recent workflow runs with filtering - View detailed run information - Monitor in-progress workflows **Log Analysis** - Fetch workflow run logs - Identify failing steps and jobs - Extract error messages and stack traces - Parse test failure output **Debugging Workflows** - Diagnose common failure patterns - Correlate errors with code changes - Identify flaky tests and race conditions - Analyze timing and performance issues ## Essential Commands ### List Workflow Runs ```bash # List all workflow runs gh run list # List runs for specific workflow gh run list --workflow=ci.yml # Filter by status gh run list --status=failure gh run list --status=in_progress # Filter by branch gh run list --branch=main # Combine filters gh run list --workflow=ci.yml --status=failure --limit 5 # JSON output for parsing gh run list --json databaseId,status,conclusion,name,createdAt,headBranch ``` ### View Workflow Run Details ```bash # View specific run gh run view <run-id> # View failed logs only gh run view <run-id> --log-failed # View specific job gh run view <run-id> --job=<job-id> # JSON output gh run view <run-id> --json status,conclusion,jobs,startedAt,updatedAt ``` ### Download and Analyze Logs ```bash # Download logs for run gh run download <run-id> # View failed step logs only gh run view <run-id> --log-failed # Extract specific job logs gh api repos/:owner/:repo/actions/runs/<run-id>/logs | less ``` ### Watch Running Workflows ```bash # Watch workflow progress gh run watch <run-id> # Watch with exit status gh run watch <run-id> --exit-status ``` ### Rerun Workflows ```bash # Rerun entire workflow gh run rerun <run-id> # Rerun only failed jobs gh run rerun <run-id> --failed # Rerun with debug logging gh run rerun <run-id> --debug ``` ### Cancel Workflows ```bash # Cancel specific run gh run cancel <run-id> ``` ## Analysis Patterns ### Find Recent Failures ```bash # Get last 10 failed runs gh run list --status=failure --limit 10 # Get failures with details gh run list --workflow=ci.yml --status=failure --limit 5 \ --json databaseId,conclusion,name,createdAt,headBranch,headSha ``` ### Identify Flaky Tests ```bash # Get runs for specific commit gh run list --commit=<sha> # Find tests that sometimes pass gh run list --workflow=test.yml --limit 20 --json conclusion \ | jq 'group_by(.conclusion) | map({conclusion: .[0].conclusion, count: length})' ``` ### Extract Error Messages ```bash # View failed logs gh run view <run-id> --log-failed # Extract error lines gh run view <run-id> --log-failed | grep -i "error\|failed\|exception" # Parse JSON for errors gh api repos/:owner/:repo/actions/runs/<run-id>/jobs \ | jq '.jobs[] | select(.conclusion == "failure") | {name, steps: [.steps[] | select(.conclusion == "failure")]}' ``` ### Read job conclusions, not the workflow's A run's `conclusion: success` also covers jobs that were **skipped**. Jobs gated on a tag push or a release event (`if: github.event_name == 'push'`, `if: startsWith(github.ref, 'refs/tags/')`, release-please pre-release only) report `skipped` on every PR, so PR CI is green for them by construction. A change that breaks one merges cleanly and fails on the next release, which can be weeks later. ```bash gh run view <run-id> --json jobs --jq '.jobs[] | {name, conclusion}' ``` - To judge whether a specific job (an image build, a release upload) actually ran, read that job's `conclusion`. `skipped` means it verified nothing. - Before merging a change to a release-gated job, exercise it: trigger it with `workflow_dispatch`, push a throwaway tag, or run the step locally (for example `docker build --file <Dockerfile> .`). ### Check Workflow Timing ```bash # Get run duration gh run view <run-id> --json startedAt,completedAt,durationMs # Compare run times gh run list --workflow=ci.yml --limit 10 \ --json databaseId,createdAt,updatedAt,durationMs \ | jq '.[] | {id: .databaseId, duration_min: (.durationMs / 60000)}' ``` ### Monitor Workflow Status ```bash # Check current status gh run list --status=in_progress # Summary of run statuses gh run list --limit 50 --json conclusion \ | jq 'group_by(.conclusion) | map({conclusion: .[0].conclusion, count: length})' ``` ## Common Failure Pattern Summary | Pattern | Symptoms | Quick Fix | |---------|----------|-----------| | Authentication | "403 Forbidden", "Resource not accessible" | Check GITHUB_TOKEN scope, workflow permissions | | Timeout | "exceeded maximum execution time" | Increase timeout-minutes, split parallel jobs | | Flaky tests | Same test passes/fails inconsistently | Fix race conditions, mock external deps | | Dependency install | "Could not find package", "Version conflict" | Lock versions, use cache | | Environment | "Command not found", "Module not found" | Verify setup steps, check runner version | | Resource constraints | "out of disk space", "Process killed" | Clean artifacts, increase runner size | ## Agentic Optimizations | Context | Command | |---------|---------| | Quick failure check | `gh run list --status=failure --limit 5 --json databaseId,conclusion,name` | | Failed logs only | `gh run view <id> --log-failed` | | JSON run details | `gh run view <id> --json status,conclusion,jobs` | | Failure rate | `gh run list --limit 50 --json conclusion \| jq 'group_by(.conclusion)'` | | Rerun failed only | `gh run rerun <id> --failed` | | Per-job conclusions | `gh run view <id> --json jobs --jq '.jobs[] \| {name, conclusion}'` | ## Quick Reference ### gh run Commands - `gh run list` - List workflow runs - `gh run view <id>` - View run details - `gh run watch <id>` - Watch run progress - `gh run download <id>` - Download logs/artifacts - `gh run rerun <id>` - Rerun workflow - `gh run cancel <id>` - Cancel running workflow ### Useful Filters - `--workflow=<name>` - Specific workflow - `--status=<status>` - Filter by status (in_progress, completed, queued, waiting) - `--conclusion=<conclusion>` - Filter by conclusion (success, failure, cancelled, skipped) - `--branch=<branch>` - Specific branch - `--event=<event>` - Specific trigger event - `--limit=<n>` - Limit results - `--json <fields>` - JSON output ### Status Values - `queued` - Waiting to start - `in_progress` - Currently running - `completed` - Finished (check conclusion) - `waiting` - Waiting for approval ### Conclusion Values - `success` - All jobs succeeded - `failure` - At least one job failed - `cancelled` - Manually cancelled - `skipped` - Skipped (conditional) - `timed_out` - Exceeded time limit ## Integration with Other Skills This skill complements: - **claude-code-github-workflows** - Creating workflows - **github-actions-mcp-config** - MCP configuration - **github-actions-auth-security** - Authentication setup ## Resources - **gh CLI Manual**: https://cli.github.com/manual/gh_run - **GitHub Actions API**: https://docs.github.com/en/rest/actions - **Troubleshooting Guide**: https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows