gh workflow run Command Reference

Trigger a workflow_dispatch run from the command line.

gh workflow run starts a workflow that has a workflow_dispatch trigger. It is how one pipeline kicks off another, with inputs and a chosen ref.

What it does

gh workflow run dispatches a workflow by name or file, on a given ref, passing inputs the workflow declares under workflow_dispatch.inputs. The target workflow must include a workflow_dispatch trigger or the call is rejected.

Common flags and usage

[workflow]: workflow name, ID, or filename (for example deploy.yml)
--ref BRANCH: branch or tag to run on
--field KEY=VALUE / -f: pass a workflow input
--raw-field / -F: pass an input without type coercion
--repo OWNER/REPO: target another repository

Example

shell

- name: Trigger deploy
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: gh workflow run deploy.yml --ref main -f environment=prod

In CI

Use gh workflow run to chain pipelines (build then deploy) or to trigger a deploy in another repo with --repo. The triggered run is asynchronous, so follow it with gh run watch when you need to block on the result.

Key takeaways

The target workflow must declare a workflow_dispatch trigger.
-f passes declared inputs; --ref selects the branch or tag.
The dispatch is async; pair with gh run watch to wait for completion.