The “gh run” command is part of GitHub CLI (Command-Line Interface) and provides a set of functionalities to view, run, and monitor recent workflow runs for GitHub Actions directly from the command-line interface. GitHub Actions is a powerful automation and workflow tool provided by GitHub that allows developers to define and run custom workflows for their repositories.
With the “gh run” command, users can perform the following actions:
- View Recent Workflow Runs: Users can use the “gh run list” command to retrieve a list of recent workflow runs for a repository. This command provides information such as the run ID, status (e.g., success, failure, in progress), workflow name, branch, and other relevant metadata. This allows users to quickly get an overview of the recent activity and status of their workflows.
- View Detailed Run Information: Users can view detailed information about a specific workflow run using the “gh run view” command. This provides more comprehensive details about the run, including the jobs, steps, and their execution status. Users can also access information such as the commit SHA, event that triggered the workflow, and artifacts generated during the run.
- Rerun Workflow Runs: The “gh run rerun” command enables users to rerun a specific workflow run. This is useful when users want to repeat a previously executed workflow run with the same configuration and parameters. It simplifies the process of retesting or retriggering a workflow run without needing to manually set up the same environment and inputs.
- Watch Workflow Runs: Users can monitor the progress of a workflow run using the “gh run watch” command. This displays real-time updates on the status and execution of the workflow run, including the output of individual steps as they are executed. It provides a convenient way to track the progress of long-running or complex workflows directly from the command-line interface.
- Filter Workflow Runs: The “gh run list” command supports filtering options to narrow down the list of displayed workflow runs based on various criteria. Users can filter by branch, status, workflow name, and other parameters to focus on specific subsets of workflow runs. This helps users quickly find the runs they are interested in and retrieve the relevant information.
- Debug Workflow Runs: The “gh run debug” command allows users to initiate a debugging session for a specific workflow run. This opens a live debugging environment where users can interactively debug the workflow run by stepping through individual steps, inspecting variables, and troubleshooting any issues encountered during the execution.
The “gh run” command provides a convenient way to interact with GitHub Actions workflow runs directly from the command-line interface. It enables users to quickly retrieve information about recent runs, rerun workflows, monitor execution progress, and even debug workflows when needed. This streamlines the workflow development and troubleshooting process by reducing the need to switch between the command-line interface and the GitHub web interface.
It is important to note that the availability and functionality of the “gh run” command may depend on the version of GitHub CLI and the specific GitHub Actions features enabled for the repository. Users should refer to the official GitHub CLI documentation for the most up-to-date information and usage guidelines.
gh run view Command Examples
1. Interactively select a run to see information about the jobs:
# gh run view
2. Display information about a specific run:
# gh run view workflow_run_number
3. Display information about the steps of a job:
# gh run view --job=job_number
4. Display the log of a job:
# gh run view --job=job_number --log
5. Check a specific workflow and exit with a non-zero status if the run failed:
# gh run view workflow_run_number --exit-status && echo "run pending or passed"
6. Interactively select an active run and wait until it’s done:
# gh run watch
7. Display the jobs for a run and wait until it’s done:
# gh run watch workflow_run_number
8. Re-run a specific workflow:
# gh run rerun workflow_run_number