gh workflow run Trigger a GitHub Actions workflow manually
Starts a workflow that has a workflow_dispatch trigger, optionally on a chosen branch and with input values. Use it for deploys and other on-demand jobs.
Synopsis
gh workflow run {WORKFLOW | ID} [FLAGS]
gh workflow listCommon options
| Option or form | What it does |
|---|---|
-r, --ref BRANCH | Branch or tag to run the workflow on |
-f, --raw-field KEY=VALUE | Set a workflow input as text (repeatable) |
-F, --field KEY=VALUE | Set an input, with @file to read from a file |
--json | Read the inputs as JSON from standard input |
gh workflow list | A separate command that lists the workflows in the repository |
Examples
gh workflow listBuild active 1234
Deploy active 5678gh workflow run deploy.ymlgh workflow run deploy.yml --ref release/1.2 -f environment=staginggh run watchNotes
- The workflow file must contain "on: workflow_dispatch", or gh reports it cannot be run.
- The command starts the run and returns. Use gh run list to find it.
- Disable or enable a workflow with gh workflow disable and gh workflow enable.
See also
Last reviewed 2026-10-09.