How to use the command "gh run" (with examples)
The command “gh run” is a GitHub CLI command that allows users to view, run, and watch recent GitHub Actions workflow runs. It provides various options to interactively select and display information about runs, jobs, and logs. This article will illustrate each of these use cases with examples.
Use case 1: Interactively select a run to see information about the jobs
Code:
gh run view
Motivation: This use case is useful when you want to interactively select a specific run to view information about the jobs associated with it. It allows you to get an overview of the executed jobs and their statuses.
Explanation:
gh run view: This command is used to view information about a specific run. When executed without any arguments, it lists recent runs and prompts you to select a run interactively.
Example output:
? View which run?
> workflow_run_number1
workflow_run_number2
...
Use case 2: Display information about a specific run
Code:
gh run view workflow_run_number
Motivation: This use case is helpful when you want to view detailed information about a specific run. It allows you to check the status, duration, and other details of a run.
Explanation:
gh run view: This command is used to view information about a specific run.workflow_run_number: The argument “workflow_run_number” specifies the identifier of the run you want to view.
Example output:
Run summary:
Run ID: workflow_run_number
Status: completed
Conclusion: success
Started: 2021-01-01T00:00:00Z
Completed: 2021-01-01T00:01:05Z
Duration: 1m 5s
...
Use case 3: Display information about the steps of a job
Code:
gh run view --job=job_number
Motivation: This use case is useful when you want to get detailed information about the steps within a specific job. It allows you to see the status, duration, output, and other information about each step.
Explanation:
gh run view: This command is used to view information about a specific run.--job=job_number: The option “–job” followed by the “job_number” argument specifies the job within the run for which you want to display the steps.
Example output:
Steps for job job_number:
Step 1: Checkout code
Status: completed
Conclusion: success
Started: 2021-01-01T00:00:00Z
Completed: 2021-01-01T00:00:10Z
Duration: 10s
Step 2: Build
Status: completed
Conclusion: success
Started: 2021-01-01T00:00:10Z
Completed: 2021-01-01T00:00:30Z
Duration: 20s
...
Use case 4: Display the log of a job
Code:
gh run view --job=job_number --log
Motivation: This use case is beneficial when you want to check the log output of a specific job within a run. It allows you to inspect the detailed log messages generated during the job execution.
Explanation:
gh run view: This command is used to view information about a specific run.--job=job_number: The option “–job” followed by the “job_number” argument specifies the job within the run for which you want to display the log.--log: The option “–log” instructs the command to display the log output of the specified job.
Example output:
Log for job job_number:
2021-01-01T00:00:10Z: Executing step "Checkout code"
2021-01-01T00:00:20Z: Checkout complete
2021-01-01T00:00:30Z: Executing step "Build"
2021-01-01T00:00:40Z: Build complete
...
Use case 5: 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: This use case is useful when you want to programmatically check the status of a specific workflow run. It allows you to exit the script or pipeline with a non-zero status if the run fails. The “echo” command following the “gh run” command is just an example, but it can be replaced with your own command or logic.
Explanation:
gh run view: This command is used to view information about a specific run.workflow_run_number: The argument “workflow_run_number” specifies the identifier of the run you want to view.--exit-status: The option “–exit-status” causes the command to exit with a non-zero status if the run failed.&&: Used to combine commands, the second command (“echo”) is executed only if the first command (“gh run view”) is successful.
Example output:
Run summary:
Run ID: workflow_run_number
Status: completed
Conclusion: failure
Started: 2021-01-01T00:00:00Z
Completed: 2021-01-01T00:01:05Z
Duration: 1m 5s
Error: run failed
Use case 6: Interactively select an active run and wait until it’s done
Code:
gh run watch
Motivation: This use case is useful when you want to keep track of an active run and wait until it completes. It provides a convenient way to monitor the progress of a workflow in real-time.
Explanation:
gh run watch: This command is used to interactively select an active run and wait for it to finish.
Example output:
? Watch which run?
> workflow_run_number1
workflow_run_number2
...
Waiting for the selected run to complete...
Use case 7: Display the jobs for a run and wait until it’s done
Code:
gh run watch workflow_run_number
Motivation: This use case is similar to the previous one but focuses on a specific run. It allows you to observe the status of all jobs within that run until they are completed.
Explanation:
gh run watch: This command is used to interactively select an active run and wait for it to finish.workflow_run_number: The argument “workflow_run_number” specifies the identifier of the run for which you want to display the jobs and wait.
Example output:
Jobs for run workflow_run_number:
Job 1: job_number1 (status: completed)
Job 2: job_number2 (status: in_progress)
Job 3: job_number3 (status: completed)
...
Waiting for the selected run to complete...
Use case 8: Re-run a specific workflow
Code:
gh run rerun workflow_run_number
Motivation: This use case is helpful when you want to re-run a specific workflow. It provides an easy way to trigger the execution of a workflow again, allowing you to test changes or retry a failed run.
Explanation:
gh run rerun: This command is used to re-run a specific workflow.workflow_run_number: The argument “workflow_run_number” specifies the identifier of the run you want to rerun.
Example output:
Re-running workflow workflow_run_number...
Conclusion:
The “gh run” command provides a versatile set of options to view, run, and watch GitHub Actions workflow runs. It allows you to interactively select and display information about runs, jobs, and logs. By understanding and utilizing these different use cases, you can efficiently manage and monitor your GitHub Actions workflows.
