gh-run

View, list, and manage GitHub Actions runs

TLDR

Interactively select a run to see information about the jobs

$ gh run view

Display information about a specific run

$ gh run view [workflow_run_number]

Display information about the steps of a job

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

Display the log of a job

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

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"]

Interactively select an active run and wait until it's done

$ gh run watch

Display the jobs for a run and wait until it's done

$ gh run watch [workflow_run_number]

Re-run a specific workflow

$ gh run rerun [workflow_run_number]

list
    List recent workflow runs.

view
    View a specific workflow run.

download
    Download artifacts associated with a workflow run.

watch
    Watch a workflow run in real-time.

rerun
    Rerun a workflow run.

cancel
    Cancel a workflow run.

run
    Run a specific workflow. 'workflow' can be the workflow name or workflow file name.

--repo
    Specify the repository. Defaults to current repository.

--branch
    Specify the branch for which workflows are displayed.

DESCRIPTION

The gh run command allows you to interact with and manage GitHub Actions workflows and workflow runs directly from your terminal.

You can view recent workflow runs, trigger new runs for specific workflows, view logs for individual jobs, and even attempt to run workflows locally for debugging and testing.

This local execution capability is especially useful for identifying issues in your workflow definitions without constantly pushing changes to your repository.

It provides a streamlined workflow for development, debugging, and management of GitHub Actions, making it easier to automate your software development lifecycle.

CAVEATS

Local workflow execution might not perfectly replicate the GitHub Actions environment. Some features or environment variables may differ, especially in regards to secrets and external service integrations. Also, not all workflow functionality can be executed locally.

LOCAL EXECUTION CONSIDERATIONS

When running workflows locally, ensure that your local environment is properly configured with any necessary dependencies, environment variables, and authentication credentials.

Use the --debug flag for more detailed output during local workflow execution.

AUTHENTICATION

Ensure that the gh CLI is properly authenticated with your GitHub account. Use gh auth login to authenticate.

HISTORY

The gh run command was introduced as part of the GitHub CLI (gh) tool to simplify interaction with GitHub Actions from the command line.

Its development reflects the growing adoption of GitHub Actions for CI/CD and automation, providing a more efficient way for developers to manage and debug workflows.