July 15, 2025

Automating GitHub Actions Workflows with the gh CLI

GitHub Actions is a powerful feature of GitHub that enables automation of software workflows directly in your repository. Whether you’re running tests, deploying code, or performing scheduled tasks, Actions can help streamline your DevOps process.

But did you know you can trigger these workflows directly from the command line using the GitHub CLI (gh)? This opens the door to scripting, local automation, and rapid testing of manual workflows—all without leaving your terminal.

In this post, we’ll walk through how to use the gh CLI to trigger a GitHub Actions workflow and pass inputs dynamically.

What Is GitHub Actions?

GitHub Actions is a CI/CD (Continuous Integration/Continuous Deployment) platform built into GitHub. It allows you to define workflows in YAML files located in your repository’s .github/workflows/ directory.

Each workflow can respond to different triggers, such as:

Push or pull request events
Scheduled cron jobs
Manual triggers via workflow_dispatch

Workflows are composed of jobs, which run in GitHub-hosted runners or self-hosted environments. You can run shell scripts, Docker containers, or any tooling needed to automate tasks.

What Is the GitHub CLI (`gh`)?

The GitHub CLI (gh) is a command-line tool that brings GitHub to your terminal. With gh, you can:

Create issues and pull requests
View workflows and logs
Trigger GitHub Actions workflows
And much more

To install it, visit cli.github.com and follow the instructions for your platform.

Once installed, you can authenticate using:

gh auth login

1	gh auth login

Running a Workflow with `gh`

You can manually trigger a workflow using the following syntax:

gh workflow run <workflow_file> --ref <branch> [--field <input_name>=<value> ...]

1	gh workflow run <workflow_file> --ref <branch> [--field <input_name>=<value> ...]

Requirements

Before you can manually trigger a workflow, make sure:

Your workflow uses the workflow_dispatch trigger.
Inputs are defined (if needed).

Here’s an example of a valid workflow file (deploy.yml):

name: Deploy to Environment

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        default: 'production'
      deploy_app:
        description: 'Deploy app?'
        required: false
        default: 'true'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to ${{ github.event.inputs.environment }}"

name: Deploy to Environment

on:

workflow_dispatch:

inputs:

environment:

description: 'Target environment'

required: true

default: 'production'

deploy_app:

description: 'Deploy app?'

required: false

default: 'true'

jobs:

deploy:

runs-on: ubuntu-latest

steps:

- run: echo "Deploying to ${{ github.event.inputs.environment }}"

Triggering the Workflow

Let’s say you want to run the above workflow on the main branch and pass in specific input values:

gh workflow run deploy.yml --ref main \
  --field environment=staging \
  --field deploy_app=false

gh workflow run deploy.yml --ref main \

--field environment=staging \

--field deploy_app=false

This command does the following:

deploy.yml: Specifies the name of the workflow file in .github/workflows/
--ref main: Indicates the branch the workflow should run on
--field: Passes values for the defined workflow_dispatch.inputs

Discovering Workflows and Inputs

To list all workflows in your repository:

gh workflow list

1 2	gh workflow list

To view the details and YAML definition of a specific workflow:

gh workflow view deploy.yml --yaml

1 2	gh workflow view deploy.yml --yaml

This is helpful for confirming input names, defaults, and descriptions before triggering the workflow.

Why Use the `gh` CLI?

Using the GitHub CLI is ideal for:

Running workflows as part of local or automated scripts
Triggering test or deploy jobs without needing to push new code
Integrating with CI/CD tools outside of GitHub (e.g., Jenkins, CircleCI)
Empowering QA, support, or project managers with limited Git experience to trigger automated processes

Final Thoughts

Triggering GitHub Actions from the command line adds flexibility and control to your development and deployment workflows. Whether you’re debugging a CI job or deploying to a staging environment, the gh CLI puts powerful automation at your fingertips.

Pro tip: You can also create shell scripts or Makefile targets that wrap gh workflow run commands, making frequent workflows as simple as typing make deploy-staging.

If your organization needs help building, maintaining, or automating your development infrastructure, Reliable Penguin is here to help. We specialize in managed hosting and DevOps solutions for developers, agencies, and businesses who rely on reliable, secure systems.