tonedefdev/opendepot/gh-actions-debug

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