Inspect and Trigger GitHub Actions Workflows with gh

Find a GitHub Actions workflow with gh, check the file and ref you are about to use, then request a manual run with the right inputs. The examples target GitHub CLI 2.87.3, installed here in February 2026.

Allow about ten minutes for a repository you can read. You need the gh command, network access to GitHub, and authentication that can read the repository. Triggering a workflow also needs the permissions GitHub grants to your account. These commands act on a remote repository, so check the repository and ref before any command that changes state.

1. Check the installed command

Start with read-only checks. They do not need elevated privileges:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh workflow --help

The workflow command has five subcommands: list, view, run, enable and disable. A failed request may mean authentication is required, not that the workflow is missing. The installed manual documents exit status 4 for that case.

2. List workflows, including disabled ones

List the enabled workflows in a repository:

$ gh workflow list --repo OWNER/REPO
NAME                         STATE   ID
Build                        active  123456
Release                      active  234567

The names, states and IDs are examples; your output depends on the repository. Listing hides disabled workflows by default, which is an easy source of confusion. Add --all when a workflow you expect is absent:

$ gh workflow list --repo OWNER/REPO --all
$ gh workflow list --repo OWNER/REPO --json id,name,path,state

The JSON form gives the fields this version supports: id, name, path and state. Use the path or numeric ID in later commands when two workflow names are similar. The default list limit is 50; use --limit 100 only when you have a reason to fetch more.

3. Inspect the exact workflow and ref

View a workflow summary by its filename, name or ID:

$ gh workflow view WORKFLOW.yml --repo OWNER/REPO
$ gh workflow view WORKFLOW.yml --repo OWNER/REPO --yaml

The first form shows the summary. The second displays the YAML file. If the file differs between branches, select the ref explicitly:

$ gh workflow view WORKFLOW.yml --repo OWNER/REPO --ref main --yaml

This is the safety boundary before a manual run. Confirm three things:

• The filename. It is the workflow you meant.
• The branch or tag. It holds the version of the file you expect.
• An on.workflow_dispatch trigger. Without it, gh workflow run cannot start the workflow.

Use --web instead of --yaml if you would rather open the workflow in a browser.

4. Trigger a manual run with a ref

For a workflow with no required inputs, give the file and repository:

$ gh workflow run WORKFLOW.yml --repo OWNER/REPO --ref main
https://github.com/OWNER/REPO/actions/runs/345678

The URL is returned when available. If you omit --ref, the workflow file comes from the remote repository's default branch. That default is not necessarily main, so specify the ref when the choice matters.

Pass string inputs with --raw-field:

$ gh workflow run deploy.yml --repo OWNER/REPO --ref release \
    --raw-field environment=staging \
    --raw-field version=2026.09.24

The equivalent --field option follows the API's @ handling. Treat values as data and quote anything the shell might interpret. Do not paste secrets into a command that can land in shell history; use the repository's supported secret mechanism for credentials.

5. Send several inputs as JSON

For structured or repeatable input, pipe JSON on standard input and add --json:

$ printf '%s\n' '{"environment":"staging","version":"2026.09.24"}' \
    | gh workflow run deploy.yml --repo OWNER/REPO --ref release --json
https://github.com/OWNER/REPO/actions/runs/345679

The JSON keys must match the workflow's declared inputs. If the workflow performs a deployment, migration or other irreversible action, validate the values locally before dispatching.

6. Handle disabled workflows

A disabled workflow is hidden from the ordinary list and cannot run. Re-enable it only after checking why it was disabled and what its next event will do:

$ gh workflow enable WORKFLOW.yml --repo OWNER/REPO
$ gh workflow list --repo OWNER/REPO --all
NAME                         STATE   ID
Deploy                       active  456789

Disabling is also a remote state change. It stops the workflow running and removes it from the default list:

$ gh workflow disable WORKFLOW.yml --repo OWNER/REPO
$ gh workflow enable WORKFLOW.yml --repo OWNER/REPO

The second command is the recovery action for this example.

Common failure checks

• Authentication requested. Log in with the organisation's approved method before retrying. Do not put a token in a command argument.
• Workflow missing. Repeat the list with --all, then inspect the exact path returned by the JSON output.
• Run rejected. Check that the file contains on.workflow_dispatch, that the ref contains that version of the file, and that each input key is exact.
• Ambiguous name. Use the numeric workflow ID from gh workflow list --json id,name,path,state.
• Non-zero status. Keep the error text. A successful dispatch request does not mean every job will pass.