Find the GitHub Actions Run You Need with gh run list

gh run list is the fastest way to find the GitHub Actions run you actually need, out of the hundreds a busy repository can generate. The examples use the installed GitHub CLI executable, which reports version 2.87.3. The local package record names package gh version 2.45.0-1ubuntu0.3+esm3, so check the executable rather than assume those two records describe the same build.

Budget about ten minutes. You need GitHub CLI, an authenticated account with access to the repository, and a repository name in OWNER/REPO form. These are read-only queries: they do not rerun, cancel, delete or alter a workflow.

1. Choose the repository explicitly

Run the list command with --repo when your current directory is not a checked-out repository, or when you want a command that is safe to paste into a script:

$ gh run list --repo OWNER/REPO --limit 10

Replace OWNER/REPO with a real repository, such as octo-org/example. Without --repo, gh tries to infer the repository from the current directory. That is convenient interactively, but it fails in an ordinary directory and can point at the wrong remote in a copied script.

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh run list --help

The default is a maximum of 20 runs. Set --limit deliberately when a person will read the result or a script will consume it. A limit controls how many runs gh fetches; it is not a guarantee the returned list covers every historical run.

2. Narrow the list before reading it

Filters can be combined. For example, find recent runs for one workflow on one branch:

$ gh run list --repo OWNER/REPO \
    --workflow build.yml \
    --branch main \
    --limit 10

• --workflow accepts a workflow name or file reference supported by gh.
• --branch filters the head branch.
• --event push selects the trigger.
• --status failure finds failures.
• --user LOGIN finds runs triggered by a user.
• --commit SHA follows one commit.

For a date boundary, pass the date expression accepted by the installed CLI:

$ gh run list --repo OWNER/REPO --created '2026-09-01..2026-09-23' --limit 50

Use a quoted date expression so shell characters do not get interpreted. If the result is empty, remove one filter first and check the workflow name with gh workflow list --repo OWNER/REPO. A disabled workflow is a common trap: the current CLI help says naming a workflow with --workflow does not fetch disabled workflows unless you also pass --all.

3. Switch to JSON when the output has a job

Human-readable columns are useful at a terminal. Scripts should request named fields instead of parsing spacing or display text:

$ gh run list --repo OWNER/REPO \
    --workflow build.yml \
    --status failure \
    --limit 20 \
    --json databaseId,displayTitle,status,conclusion,headBranch,createdAt,url

The result is a JSON array. Its values depend on the repository and the runs returned, but each object contains the fields you requested. Keep the field list short: it makes the output easier to review and reduces the chance that a later display change breaks your script.

$ gh run list --repo OWNER/REPO --limit 20 \
    --json status,url \
    --jq '.[] | select(.status == "completed") | .url'

--jq filters JSON output inside gh. It does not change which runs are fetched, so put a sufficiently high --limit on the command when the filter might discard many entries. An empty result can mean either that no fetched run matched, or that the limit was too small.

4. Make a repeatable failure check

To print a compact record for failed workflow runs, ask for the fields the next step needs and format them with jq:

$ gh run list --repo OWNER/REPO \
    --status failure \
    --limit 20 \
    --json databaseId,workflowName,headBranch,createdAt,url \
    --jq '.[] | [.databaseId, .workflowName, .headBranch, .createdAt, .url] | @tsv'

This produces tab-separated values, one run per line. The expression is applied after gh has fetched its limited result set. If you need the run's jobs or logs, pass the selected database ID to a separate read command such as gh run view RUN_ID --repo OWNER/REPO; gh run list is a discovery command, not a log viewer.

5. Read the result without overclaiming

A successful list command means gh retrieved a list. It does not mean the runs succeeded. Check both status and conclusion in the JSON: a run can be in progress with no final conclusion yet, while a completed run normally has a conclusion such as success, failure or cancelled.

Workflow names can be missing for runs created by organisation and enterprise ruleset workflows, due to a GitHub API limitation. If a row has an empty workflow name, use its URL, database ID, branch and commit to identify it, rather than treating the blank as proof no workflow ran.

Pull request checks are another boundary. For checks associated with a pull request, the installed help points you to gh pr checks. Do not infer pull request health from a short, branch-filtered run list when the pull request command can give you the relevant check view directly.