How to Use the Command 'gh run' (with examples)

The ‘gh run’ command is part of the GitHub CLI that allows users to interact with GitHub Actions workflow runs directly from the terminal. This tool provides several functionalities, including viewing detailed information about workflows, checking their status, and even re-running them when necessary. By enabling direct command-line operations on workflows, ‘gh run’ becomes a powerful tool for developers looking to streamline their continuous integration and delivery processes.

Interactively Select a Run to See Information about the Jobs

Code:

gh run view

Motivation: Sometimes, developers need a quick way to get a detailed view of recent workflow runs to understand their state and performance. This command is particularly useful when managing a project with multiple workflow runs, helping developers quickly identify which runs might require attention or investigation.

Explanation: By executing gh run view without any arguments, the user is offered an interactive selection menu that lists recent workflow runs. The purpose of this interaction is to grant the user the freedom to pick a specific run to inspect its jobs and status. It streamlines navigating through multiple workflows without remembering or specifying exact references.

Example Output:

? Select a workflow run:  [Use arrows to move, type to filter]
  workflow-name 123  ✔  Completed
> workflow-name 124  ✖  Failed
  workflow-name 125  ✔  Completed

Display Information about a Specific Run

Code:

gh run view workflow_run_number

Motivation: In larger projects, there may be times when developers have to dive deeper into the specifics of a particular workflow execution to understand issues or verify changes. This command allows for pinpointed examination of a specific run by its unique identifier.

Explanation: The workflow_run_number is a unique identifier of the workflow run that you wish to inspect. Using this identifier, the command retrieves detailed information of that specific workflow run, including status, duration, and included jobs.

Example Output:

Workflow: Deploy to Production
Status: Failed
Started: 2023-04-12T10:00:00Z
Duration: 15m
Jobs:
- Build: Completed
- Test: Failed
- Deploy: Skipped

Display Information about the Steps of a Job

Code:

gh run view --job=job_number

Motivation: Being able to view detailed information about the steps within a job is crucial when troubleshooting or optimizing workflows. Developers can use this command to gain clarity about what each step in a job does and whether any particular step is failing.

Explanation: The argument --job=job_number specifies which job’s steps should be examined. This numeric identifier targets a specific job within a workflow run. The command produces detailed insights on all steps, including success or failure statuses, any attached logs, and error messages.

Example Output:

Job: Test
Steps:
- Checkout: Completed
- Install Dependencies: Completed
- Run Tests: Failed
Error: Some tests failed to execute

Display the Log of a Job

Code:

gh run view --job=job_number --log

Motivation: When trying to understand failures or bugs within a job, having direct access to the logs provides crucial information, which can guide fixes and optimizations. This capability is instrumental during active development or debugging phases.

Explanation: Adding the --log argument alongside --job=job_number specifies that the command should return the log output for the given job. Logs often contain console outputs or debug statements that offer invaluable insights into the inner workings or issues of a job.

Example Output:

Fetching logs for Job: Build
Log Output:
Step 1: Checkout - Successful
Step 2: Build - Failed
Error: Compilation error in main.c: Line 24

Check a Specific Workflow and Exit with a Non-Zero Status if the Run Failed

Code:

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

Motivation: For scenarios where workflows are part of automated scripts, exiting with non-zero status on failure enables automated error handling in shell scripts or CI/CD pipelines. This feature is crucial for integrating GitHub Actions workflows into broader automation frameworks.

Explanation: The --exit-status argument modifies the command’s behavior to produce an exit code representing the status of the workflow run. If the run failed, the command exits with a non-zero code that scripts can detect, allowing for conditional subsequent actions. The && operator in the command ensures that the echo statement runs only if the workflow passed or is pending.

Example Output:

# On failure, there is no output; failure would lead to script error handling.
# On success or pending:
run pending or passed

Interactively Select an Active Run and Wait until it’s Done

Code:

gh run watch

Motivation: This feature is useful for developers who wish to monitor active runs and prefer not to wait passively. It keeps the user informed of the workflow’s completion and status changes, ensuring that no additional check is necessary.

Explanation: By invoking gh run watch without additional arguments, users can select one or more active workflow runs to monitor interactively. It waits until the specified runs have either failed or succeeded, providing real-time updates.

Example Output:

? Select a workflow run to watch:  [Use arrows to move, type to filter]
> workflow-name 126  •  In progress
Monitoring workflow-name 126...
...
Workflow completed with status: Success

Display the Jobs for a Run and Wait until it’s Done

Code:

gh run watch workflow_run_number

Motivation: Sometimes, developers need to keep an eye on the entire workflow run, especially during critical deployments or testing periods. This command prioritizes monitoring and provides end-to-end visibility of the workflow execution without manual intervention.

Explanation: By entering a specific workflow’s workflow_run_number, the command is directed to monitor that particular run until its conclusion. It reveals detailed job progress and delivers completion notifications for the whole workflow.

Example Output:

Watching workflow: Deploy to Production
Job Statuses:
- Build: Completed
- Test: In progress
...
Test: Completed
Deploy: Completed
Workflow finished successfully.

Re-run a Specific Workflow

Code:

gh run rerun workflow_run_number

Motivation: When a workflow run needs to be repeated due to a resolved bug, test flakiness, or intentional re-testing, re-running the workflow quickly is indispensable. Rather than navigating through the web interface, this command offers a straight-through approach from the command line.

Explanation: The workflow_run_number parameter signifies the particular workflow run intended for repetition. The command initiates another attempt of the specified workflow, ensuring the developer can promptly re-execute previously defined steps under similar conditions or with updated inputs.

Example Output:

Re-running workflow: Deploy to Production
New run starting with ID: 127

Conclusion

The gh run command stands as a robust and versatile tool in a developer’s toolkit, enabling detailed interaction with GitHub Actions workflows. With its various functionalities, it helps streamline the examination, monitoring, and management of workflows directly from the command line. By providing deeper insight and efficient management capabilities, it plays an essential role in maintaining CI/CD rigor, troubleshooting runs, and ensuring successful automation pipelines.