gh-workflow

Interactively select a workflow to view the latest jobs for

$ gh workflow view

$ gh workflow view [id|workflow_name|filename.yml] [[-w|--web]]

$ gh workflow view [id|workflow_name|filename.yml] [[-y|--yaml]]

$ gh workflow view [id|workflow_name|filename.yml] [[-r|--ref]] [branch|tag_name] [[-y|--yaml]]

$ gh workflow list

$ gh workflow run [id|workflow_name|filename.yml] [--raw-field param1=value1 --raw-field param2=value2 ...]

$ echo '[{"param1": "value1", "param2": "value2", ...]}' | gh workflow run [id|workflow_name|filename.yml] [[-r|--ref]] [branch|tag_name]

$ gh workflow [enable|disable] [id|workflow_name|filename.yml]

gh workflow <subcommand> [flags]
For example: gh workflow list
For subcommand-specific help: gh workflow <subcommand> --help

--repo <[HOST/]OWNER/REPO>
    Selects a GitHub repository to operate on. If not specified, the repository of the current directory is used.

--web
    Opens the workflow or list of workflows in a web browser. Applicable to list and view subcommands.

--limit <integer>
    Limits the number of workflow runs or workflows displayed. Applicable to the list subcommand.

--all
    Lists all workflows, including disabled ones. Applicable to the list subcommand.

--ref <branch>
    The Git reference (branch, tag, or SHA) on which to dispatch a workflow run. Applicable to the run subcommand.

--field <key=value>
    Passes an input parameter as a string or JSON for a workflow dispatch. Use multiple times for multiple inputs. Applicable to the run subcommand.

--raw-field <key=value>
    Passes an input parameter directly, without JSON encoding. Applicable to the run subcommand.

--help
    Displays help information for the gh workflow command or a specific subcommand.

The gh workflow command is a powerful subcommand of the GitHub CLI, designed to interact with and manage GitHub Actions workflows directly from your terminal. It allows users to perform various operations such as listing all workflows in a repository, viewing detailed information about a specific workflow, enabling or disabling workflows, and even manually triggering a workflow run. This utility is invaluable for developers and CI/CD engineers who need to automate or troubleshoot their GitHub Actions pipelines without leaving the command line interface. It streamlines common development tasks, enhancing productivity and enabling scriptable interactions with GitHub's robust automation features.

Requires the GitHub CLI (gh) to be installed and authenticated. Appropriate GitHub repository permissions are necessary to perform workflow actions like enabling, disabling, or dispatching runs. Network connectivity to GitHub is essential for all operations.

The gh workflow command groups several subcommands to manage workflows:
list: Lists workflows in the current or specified repository.
view: Displays details of a specific workflow.
run: Manually dispatches a workflow run with optional inputs and a reference.
enable: Enables a disabled workflow.
disable: Disables an active workflow.

The gh workflow command inherits its authentication from the main gh CLI. Users typically authenticate using gh auth login, which securely stores credentials to interact with GitHub APIs.

The gh CLI, which includes the workflow subcommand, was developed by GitHub to provide a native command-line interface for interacting with GitHub services. It moved to general availability in September 2020. The workflow capabilities were integrated as GitHub Actions became a core part of the GitHub platform for CI/CD automation, offering users a consistent CLI experience for managing their automated workflows.

gh(1), gh run(1), git(1)