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

For Codex Security, an exit code of 2 with partial coverage is an incomplete scan, not a HIGH/CRITICAL threshold failure. Check the execution diagnostics in the job summary and the codex-security-diagnostics-<run>-<attempt> artifact on scan failure. It contains fixed status values, aggregate coverage counts, and disk space before, after, and the minimum sampled every five seconds. Missing coverage or manifest documents indicate no readable final report was available; deferred items or surfaces needing follow-up can explain partial coverage. Sampling cannot rule out a disk spike between samples.

Artifacts and logs in this public repository are public. Never upload the raw scan directory, report.md, coverage.json, findings, agent state, or scanner logs. Coverage reasons and notes are free text and may disclose vulnerabilities. The public diagnostic intentionally omits them; detailed review needs an approved private destination. Helpers must come from the workflow revision, not from the candidate under scan.

setup-nix retries development-shell preparation once when prepare-shell is enabled. Inspect both attempts in the job log; setup-rust assumes the shell has already been prepared. Cargo, lint, and test commands are not retried. Direct Nix builds and app dependency preparation also retry once; apps run once after preparation succeeds. Skipped dependent E2E suites indicate blocked coverage.

For Trivy Changes, inspect the Resolve PR baseline step for the base and head SHAs. PR runs compare the tested merge commit with its first parent; change detection and scans must use the same pair. On reruns, do not substitute the current main tip or the event's older PR base SHA. Merge groups and manual runs use their explicit baseline. Findings are reported by Reject new high or critical findings; distinguish those from scanner failures.

For Protobuf Compatibility, check the logged train and comparison baseline. Branch Checks compares the prospective merge tree with its target; Release Tag compares the tagged candidate with the previous stable release. Both use the shared check-protobuf-compatibility action with nix run .#check-protobuf-compatibility -- <ref>. During 0.x, a minor train permits compatibility findings as warnings; a patch train or no active train rejects them. Compare the current train's version with the latest stable release; commit messages are irrelevant. Compilation, baseline, and tool errors remain fatal. The protobuf_compatibility suite participates in the release-tag-v1 qualification profile. Both tagged pre-release and stable publication require this profile to pass. Failed, cancelled, or skipped suites block publication; build artifacts and qualification evidence remain in Actions storage for diagnosis. Source-SHA images are staging inputs for qualification. Snap builds run in parallel with qualification, but tagged stable Store uploads consume those built artifacts only after qualification passes.

For Codex Compatibility Review, inspect its job summary and the compatibility-review-run-<run-id>-attempt-<attempt> artifact. Confirm the candidate and baseline SHAs before interpreting findings. complete describes execution and coverage, not compatibility: also read the assessment and findings. An error, incomplete coverage, or missing artifact means no clean review is available. The job is advisory and independent of publication gates; the qualification summary points to it without waiting for completion. Do not rerun Release Tag to debug this reviewer. Use its dedicated manual workflow with an existing candidate tag; that path does not publish release artifacts.

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

1. Push your changes and create/update a PR
2. Watch the workflow run:

   gh run watch
   

3. If a job fails, view the failed logs:

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

4. Rerun the failed jobs if needed:

   gh run rerun <run-id> --failed