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.

Checkpoint: Confirm that the version and repository you intend to use are the ones in your shell session. The examples below use the placeholders OWNER/REPO and WORKFLOW.yml; replace both with real values.

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.

Checkpoint: Do not infer input names from the workflow's display name. Read the YAML and copy the exact input keys. A typo in an input key can produce a rejected request or an unintended run.

4. Trigger a manual run with a ref

Warning: Running a workflow creates a workflow_dispatch event. It is a remote state change and may consume runners, deploy software or publish data. There is no general undo for a dispatch, so review the workflow's jobs and target ref first, and use a test branch or the repository's documented dry-run input where available.

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.

Tip: For a first use, interactive mode also works. Run gh workflow run without a workflow argument and let the command collect the workflow and inputs.

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.

Warning: Do not use disable as an emergency substitute for understanding a production deployment. Record who changed the workflow and why, especially in a shared repository.

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.

Done means

Version and repository confirmed. You checked the installed GitHub CLI version and the target repository.
Full list seen. You listed enabled workflows and knew when to add --all.
YAML read on the right ref. You inspected it before dispatching.
Inputs exact, secrets out. You used the declared input names and kept secrets out of shell history.
State changes handled. You treated run, enable and disable as remote changes with a recovery or review step.