gh-run

Interactively select a run to see information about the jobs

$ gh run view

$ gh run view [workflow_run_number]

$ gh run view [[-j|--job]] [job_number]

$ gh run view [[-j|--job]] [job_number] --log

$ gh run view [workflow_run_number] --exit-status && [echo "run pending or passed"]

$ gh run watch

$ gh run watch [workflow_run_number]

$ gh run rerun [workflow_run_number]

gh run command [flags]

Where command is one of:
cancel <run-id> [flags]
download <run-id> [flags]
list [flags]
rerun <run-id> [flags]
view <run-id> [flags]

cancel
    Cancels a specified workflow run by its ID.

download
    Downloads artifacts generated by a specified workflow run.

list
    Lists recent workflow runs, with options to filter by workflow, branch, or status.

rerun
    Reruns a specified workflow run, or specific jobs within it.

view
    Views detailed information or logs for a specified workflow run or job.

The gh run command is a powerful subcommand within the GitHub CLI (gh), a command-line interface provided by GitHub. It is designed to streamline the management and interaction with GitHub Actions workflow runs directly from the terminal. This command group provides a convenient way to perform tasks traditionally handled via the GitHub web UI, making it invaluable for developers and CI/CD engineers. Users can leverage gh run to list recent workflow executions, inspect detailed logs of individual runs, download generated artifacts, trigger reruns of failed or successful workflows, and even cancel ongoing runs. Its functionality enhances efficiency by allowing quick monitoring, debugging, and control of automated workflows without leaving the terminal, integrating seamlessly into existing scripting environments for continuous integration and delivery.

The gh run command requires the GitHub CLI (gh) to be installed and authenticated to your GitHub account. It also necessitates an active internet connection to communicate with GitHub. Users must have appropriate repository permissions to perform actions like canceling or rerunning workflow runs. Workflow run IDs, required for many subcommands, typically need to be retrieved first, often using gh run list.

Each subcommand under gh run typically supports additional specific flags to refine its behavior. For instance, gh run list accepts filters like --workflow, --branch, or --limit. gh run download uses --dir to specify the download directory, and gh run view can use --log to show run logs. All subcommands also support the --help flag for detailed usage information.

List all recent workflow runs: gh run list
List runs for a specific workflow named 'build' on 'main' branch: gh run list --workflow build --branch main
View details of run ID 12345, including logs: gh run view 12345 --log
Download all artifacts from run ID 54321 to a directory named 'build-artifacts': gh run download 54321 --dir build-artifacts
Rerun run ID 67890: gh run rerun 67890

The gh run functionality is an integral part of the GitHub CLI, which was officially launched by GitHub to bring GitHub's features to the terminal. Its development focuses on empowering developers and CI/CD engineers to manage their GitHub Actions workflows efficiently without leaving the command line. Since its introduction, gh run has evolved with new capabilities, reflecting the growing importance of GitHub Actions in modern development workflows and the desire for streamlined command-line interfaces for continuous integration and delivery.

gh(1), gh workflow(1), git(1)