gh-actions-debug

name	gh-actions-debug
description	Use when: a GitHub Actions workflow run fails, a pipeline is stuck, a job is erroring, CI is broken, you need to fetch run logs, list workflows, trigger a workflow dispatch, cancel a run, view run history, check workflow status, manage secrets or variables, read or post pull request comments, or perform any GitHub Actions or pull request operation using the gh CLI. Triggers: 'workflow failed', 'pipeline broken', 'CI error', 'check the run logs', 'trigger the workflow', 'cancel the run', 'list workflows', 'view run history', 'what did the action output', 'why did the workflow fail', 'run the workflow', 'set a secret', 'add a variable', 'read PR comments', 'list pull request comments', 'what did someone comment on the PR', 'post a comment on the PR'.
argument-hint	What you want to do — e.g. 'debug the failing release run', 'trigger build workflow on main', 'list recent runs'

GitHub Actions & Pull Requests via gh CLI

Use the gh CLI to interact with GitHub Actions and pull requests — list, trigger, monitor, debug, cancel, and manage workflows and runs, and read or post pull request comments without leaving the terminal or needing an MCP server.

Prerequisites

• gh CLI installed and authenticated (gh auth status)
• Run from within the repository root (where .github/ lives)

---

Workflows

List all workflows in the repo

gh workflow list

View a specific workflow definition

gh workflow view <workflow-name-or-id>

Enable / disable a workflow

gh workflow enable <workflow-name-or-id>
gh workflow disable <workflow-name-or-id>

Trigger a workflow dispatch manually

gh workflow run <workflow-name-or-id> --ref <branch>

Pass inputs if the workflow defines them:

gh workflow run <workflow-name-or-id> --ref main --field environment=production

---

Runs

List recent runs (all workflows)

gh run list --limit 10

Filter by workflow, branch, status, or actor

gh run list --workflow release.yaml --limit 10
gh run list --branch main --status failure --limit 10
gh run list --user <username> --limit 10

Watch a live run stream in the terminal

gh run watch <run-id>

Cancel a run

gh run cancel <run-id>

Delete a run

gh run delete <run-id>

---

Inspecting & Debugging Runs

View run summary (jobs + their status)

gh run view <run-id>

Fetch full logs for a run

gh run view <run-id> --log

Fetch only failed step logs (best first step for debugging)

gh run view <run-id> --log-failed

List jobs in a run with statuses

gh run view <run-id> --json jobs --jq '.jobs[] | {name: .name, status: .status, conclusion: .conclusion}'

View logs for a specific job

gh run view <run-id> --job <job-id> --log

Re-run only failed jobs

gh run rerun <run-id> --failed

Re-run the entire run

gh run rerun <run-id>

---

Secrets & Variables

List secrets (names only — values are never shown)

gh secret list
gh secret list --env <environment-name>

Set a secret

gh secret set MY_SECRET --body "value"
gh secret set MY_SECRET --env production --body "value"

Delete a secret

gh secret delete MY_SECRET

List variables

gh variable list

Set a variable

gh variable set MY_VAR --body "value"

---

Debugging Workflow

When a run fails, follow this sequence:

1. gh run list --limit 10 — find the failing run ID
2. gh run view <run-id> --log-failed — read only the failed steps
3. Cross-reference with .github/workflows/<name>.yaml to understand the step context
4. Fix the workflow YAML or underlying code
5. gh run rerun <run-id> --failed to re-run without triggering a new push

Pull Request Comments

List all comments on a PR

gh pr view <pr-number> --comments

List comments as structured JSON (useful for filtering)

gh api repos/{owner}/{repo}/issues/<pr-number>/comments --jq '.[] | {id: .id, author: .user.login, body: .body, created_at: .created_at}'

Get the most recent comment on a PR

gh api repos/{owner}/{repo}/issues/<pr-number>/comments --jq '.[-1] | {author: .user.login, body: .body}'

Search comments for a specific string

gh api repos/{owner}/{repo}/issues/<pr-number>/comments --jq '.[] | select(.body | test("<search-term>"; "i")) | {author: .user.login, body: .body}'

Post a comment on a PR

gh pr comment <pr-number> --body "Your comment text here"

Post a comment from a file

gh pr comment <pr-number> --body-file comment.md

List review comments (inline code comments)

gh api repos/{owner}/{repo}/pulls/<pr-number>/comments --jq '.[] | {author: .user.login, path: .path, line: .line, body: .body}'

---

Tips

• --log-failed trims all successful step output — use it first before pulling full logs
• Run IDs appear in GitHub UI URLs: github.com/<owner>/<repo>/actions/runs/<run-id>
• Use --json with --jq on any gh run command to extract structured data
• gh run watch streams live output — useful for triggered dispatches
• For gh api commands, {owner}/{repo} is resolved automatically when run inside the repo — you can also use :owner/:repo shorthand or omit and let gh infer from git remote