gh run list: Usage, Options & Common CI Errors

List recent Actions runs - filtered by workflow, branch, or status.

gh run list shows recent workflow runs with their status and conclusion, filterable by workflow, branch, event, and actor. It is how you find a run ID to view or watch.

What it does

gh run list prints recent runs (most recent first) with status, conclusion, workflow, branch, and run ID. Filters narrow by --workflow, --branch, --event, --user, and --status; --json gives structured output for scripting downstream actions.

Common usage

# Recent runs
gh run list

# Filter by workflow, branch, and status
gh run list --workflow deploy.yml --branch main --status failure

# JSON: get the latest run's databaseId
gh run list --workflow ci.yml --limit 1 --json databaseId --jq '.[0].databaseId'

Common error in CI: invalid status value / no runs

gh run list errors with "invalid status: ..." when --status gets an unsupported value, or returns nothing when filters match no runs. Fix: use valid status values (queued, in_progress, completed) and conclusion values (success, failure, cancelled, skipped, etc.) - note status and conclusion are different fields. Loosen filters or pass --repo owner/name outside a clone. Token needs actions: read.

Key options

Related guides