Mastering GitHub CLI's Workflow Command (with examples)

The gh workflow command is part of the GitHub CLI, which enables developers to seamlessly interact with GitHub from the terminal. This command specifically deals with GitHub Actions workflows, offering capabilities such as listing, viewing, running, enabling, and disabling workflows. It’s a powerful tool for developers looking to streamline their workflow management directly from their command line interface. By mastering this command, users can enhance their efficiency and manage their CI/CD pipelines with greater ease.

Use case 1: Interactively Select a Workflow to View the Latest Jobs For

Code:

gh workflow view

Motivation: This use case is particularly useful when a developer needs a quick overview of the latest jobs associated with a workflow but isn’t sure which specific workflow they want to inspect. By launching an interactive selection, users can browse through available workflows and choose the one they are interested in, saving time and effort in searching manually.

Explanation: The view argument within the gh workflow command initiates a prompt where the user can interactively select from a list of workflows. This is particularly helpful when numerous workflows exist, or when the user does not have the specific ID or name at hand.

Example Output: Upon executing the command, a list of available workflows will appear in the terminal. The user will be able to navigate and select a workflow to get the latest job details, similar to a menu-driven interface within the terminal.

Use case 2: View a Specific Workflow in the Default Browser

Code:

gh workflow view id|workflow_name|filename.yml --web

Motivation: Sometimes, visualizing the workflow through GitHub’s web interface can provide better insights, especially when dealing with complex configurations or integrated tools that are easier to understand visually. Using the --web flag directs the user to the browser, offering a more comprehensive and user-friendly display.

Explanation:

• id|workflow_name|filename.yml: This argument lets the user specify the particular workflow to be viewed. It can be identified by its unique ID, its name or its file name.
• --web: This option, when appended, indicates that the result should be opened directly in the default web browser, leveraging GitHub’s intuitive UI for better clarity.

Example Output: Executing this command will automatically open the specified workflow in the default web browser, displaying an overview and the detailed structure of the workflow.

Use case 3: Display the YAML Definition of a Specific Workflow

Code:

gh workflow view id|workflow_name|filename.yml --yaml

Motivation: Understanding the configuration and setup of a workflow can be crucial for debugging or modification. By viewing the YAML definition directly in the terminal, developers can quickly navigate and comprehend the structure and parameters set within a workflow without leaving the command line.

Explanation:

• id|workflow_name|filename.yml: Specifies the workflow for which the YAML definition needs to be retrieved.
• --yaml: This flag instructs the command to display the workflow’s YAML file, a human-readable format showcasing the entire configuration.

Example Output: The terminal will present the YAML content of the specified workflow, allowing users to see parameters, jobs, and triggers defined in the workflow.

Use case 4: Display the YAML Definition for a Specific Git Branch or Tag

Code:

gh workflow view id|workflow_name|filename.yml --ref branch|tag_name --yaml

Motivation: Workflows may vary between branches or versions in a project. By viewing the YAML definition of a specific branch or tag, users can ensure that they understand changes or differences between versions, which is useful for tasks such as feature development, bug fixes, or version-specific deployment strategies.

Explanation:

• id|workflow_name|filename.yml: Identifies the target workflow.
• --ref branch|tag_name: Specifies the branch or tag from which to extract the workflow’s YAML definition, crucial for examining workflows in the context of a particular development stage or release.
• --yaml: Directs the command to present the configuration in the YAML format.

Example Output: The terminal output will show the YAML representation of the workflow, as it exists in the specified branch or tag, providing insights into variant setups across different code stages.

Use case 5: List Workflow Files (Including Disabled Workflows)

Code:

gh workflow list

Motivation: Listing all available workflows, including those that are currently disabled, grants users a comprehensive overview of all workflow possibilities within their repository. This is beneficial for maintaining an understanding of the complete CI/CD setup and for re-evaluating or re-enabling workflows as needed.

Explanation:

• The command lists all workflows present in a repository, omitting disabled workflows by default.
• Adding the --all flag would modify the command to also include those workflows that have been disabled, providing a fuller picture.

Example Output: The terminal will display a list of workflows, with details such as their IDs, file names, and current status (enabled or disabled). If --all is added, disabled workflows will also appear in the list.

Use case 6: Run a Manual Workflow with Parameters

Code:

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

Motivation: Initiating workflows manually with specific parameters is essential for testing scenarios, deploying fixes, or customizing workflow execution to meet unique criteria. By setting these parameters, users can simulate different conditions and outcomes, enhancing testing and deployment processes.

Explanation:

• id|workflow_name|filename.yml: Determines which workflow is to be manually executed.
• --raw-field param=value: This allows passing specific parameters as raw fields, enabling customization of the workflow’s execution based on the given values.

Example Output: The terminal will confirm the initiation of the workflow, possibly displaying the ID of the new run or details about the parameters used. No immediate output might display if the workflow’s execution is asynchronous.

Use case 7: Run a Manual Workflow Using a Specific Branch or Tag with JSON Parameters

Code:

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

Motivation: This scenario allows greater flexibility by running workflows with JSON-defined parameters, particularly beneficial for complex parameter sets or when managing configurations through scripts or external processes. Targeting a specific branch or tag further increases the capability to test or deploy exact mixes of application code and workflow parameterization.

Explanation:

• echo '{"param1": "value1", ...}': Constructs a JSON object containing the parameters.
• The | pipe feeds this JSON data into the subsequent command.
• gh workflow run id|workflow_name|filename.yml: Specifies the workflow to run.
• --ref branch|tag_name: Identifies the specific branch or tag environment for the execution, crucial for strategic testing or deployments.

Example Output: The terminal will register the workflow run request and may output a confirmation with details such as a tracking URL or run ID.

Use case 8: Enable or Disable a Specific Workflow

Code:

gh workflow enable|disable id|workflow_name|filename.yml

Motivation: Control over whether workflows are active or inactive is significant for project management. Enabling or disabling workflows can help manage resource allocation, timing for certain processes, or phases of development, ensuring that workflows align perfectly with current project needs or constraints.

Explanation:

• enable|disable: This action toggles the state of the workflow, either permitting it to run (enable) or preventing any executions (disable).
• id|workflow_name|filename.yml: Identifies which workflow’s status is being changed.

Example Output: The terminal will confirm the action taken, stating whether the workflow was successfully enabled or disabled.

Conclusion:

Mastery of the gh workflow command can significantly streamline the process of managing GitHub Actions workflows. Whether users wish to quickly view and assess workflow statuses, execute workflows with precision, or control the active workflows within their projects, these command examples provide the necessary functionalities to achieve efficient and effective CI/CD management directly from the command line.