gh workflow run: Usage, Options & Common CI Errors

Manually trigger a workflow_dispatch run from the CLI.

gh workflow run triggers a workflow that has a workflow_dispatch trigger, optionally passing inputs and choosing the ref it runs on.

What it does

gh workflow run <workflow> dispatches a run of a workflow identified by file name, name, or ID. It targets a branch/tag with --ref and passes inputs with -f key=value (or --json from stdin). The workflow must already declare an on: workflow_dispatch trigger.

Common usage

# Trigger by workflow file name
gh workflow run deploy.yml

# Pass inputs and pick the ref
gh workflow run deploy.yml --ref main -f environment=prod -f version=1.2.0

# Pass inputs as JSON via stdin
echo '{"environment":"prod"}' | gh workflow run deploy.yml --json

Common error in CI: workflow does not have workflow_dispatch / 403

gh workflow run fails with "workflow does not have \"workflow_dispatch\" trigger" when the target workflow lacks that trigger, or 403 when the token lacks the workflow scope. Fix: add on: workflow_dispatch: (declaring any inputs you pass) to the workflow on the target ref, and use a token with the workflow scope (actions: write permission). The default GITHUB_TOKEN can dispatch workflows in the same repo when given actions: write.

Key options

Related guides