Watch Github Actions

Watch GitHub Actions

Monitor GitHub Actions workflow runs using the gh CLI.

Prerequisites

• The gh CLI must be authenticated (gh auth status)
• You must be in a git repository with a GitHub remote

Quick Status Check

List recent workflow runs for the current branch:

gh run list --branch "$(git branch --show-current)"

List all recent runs:

gh run list

Watch a Run in Real Time

Watch a workflow run until it completes:

gh run watch

Watch a specific run:

gh run watch <run-id>

This will continuously update the status until the run finishes (success, failure, or cancelled).

View Run Details

View a specific run with job details:

gh run view <run-id>

View with full log output:

gh run view <run-id> --log

View a failed job's log:

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

Check Runs for a Specific Branch

Current branch:

gh run list --branch "$(git branch --show-current)"

Specific branch:

gh run list --branch main
gh run list --branch feature-branch

Check Runs for a PR

List workflow runs associated with a PR:

# Get the head branch of the PR, then list runs
BRANCH=$(gh pr view <pr-number> --json headRefName --jq '.headRefName')
gh run list --branch "$BRANCH"

Or view the checks directly on the PR:

gh pr checks <pr-number>

List Recent Runs

List runs for the current project:

gh run list

Filter by status:

gh run list --status failure
gh run list --status success
gh run list --status in_progress

Filter by workflow:

gh run list --workflow "CI"

JSON output for scripting:

gh run list --json databaseId,status,headBranch,url --jq '.[] | {id: .databaseId, status: .status, branch: .headBranch, url: .url}'

View Job Logs

View logs for a specific run:

gh run view <run-id> --log

View only failed job logs:

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

Wait for Run Completion (Scripting)

Watch and wait for a run to complete:

RUN_ID=$(gh run list --branch "$(git branch --show-current)" --limit 1 --json databaseId --jq '.[0].databaseId')
gh run watch "$RUN_ID" --exit-status
echo "Run finished with exit code: $?"

Open Run in Browser

Open the latest run in your default browser:

gh run view --web

Open a specific run:

gh run view <run-id> --web

Rerun Failed Jobs

Rerun all failed jobs in a run:

gh run rerun <run-id> --failed

Rerun an entire run:

gh run rerun <run-id>

Useful Commands Reference

| Command | Description |

| ----------------------------------- | --------------------------------------- |

| gh run list | List recent workflow runs |

| gh run list --branch <branch> | List runs for a specific branch |

| gh run list --status failure | List failed runs |

| gh run watch | Watch latest run until completion |

| gh run watch <run-id> | Watch a specific run until completion |

| gh run view <run-id> | View run details and job list |

| gh run view <run-id> --log | View full run logs |

| gh run view <run-id> --log-failed | View only failed job logs |

| gh run view --web | Open run in browser |

| gh run rerun <run-id> | Rerun a workflow run |

| gh run rerun <run-id> --failed | Rerun only failed jobs |

| gh run cancel <run-id> | Cancel a running workflow |

| gh pr checks <pr-number> | View PR check statuses |

Common Flags

| Flag | Description |

| ------------------- | ---------------------------------------------- |

| -b, --branch | Specify branch (default: current branch) |

| --status | Filter by status (queued, in_progress, etc.) |

| --workflow | Filter by workflow name |

| -L, --limit | Maximum number of runs to list |

| -w, --web | Open in browser |

| --json | Output as JSON with specified fields |

| --jq | Filter JSON output with jq expression |

Example Workflow

• Push your changes and create/update a PR
• Watch the workflow run:

   gh run watch

• If a job fails, view the failed logs:

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

• Rerun the failed jobs if needed:

   gh run rerun <run-id> --failed