Command referencegh workflow run
gh workflow run command (Linux & Windows / GitHub CLI)
What it does
Trigger a workflow_dispatch event for a GitHub Actions workflow. When people search for gh workflow run, they usually want practical GitHub CLI flags, safe examples, and how this subcommand fits everyday PR and repo workflows on Linux, Windows, and macOS. Syntax, options, and copyable examples are below.
Trigger a workflow_dispatch event for a GitHub Actions workflow.
Syntax
gh workflow run [<workflow-id> | <workflow-name>] [flags]
Common options
| Flag / option | Meaning |
|---|---|
| -r, --ref | Git ref to run against (branch or tag). |
| -f, --field | Input key=value pairs for workflow_dispatch inputs. |
| -F, --raw-field | Raw input fields without JSON encoding quirks. |
Practical examples
Dispatch by filename
gh workflow run ci.yml
Starts the workflow defined in .github/workflows/ci.yml when it supports dispatch.
With inputs
gh workflow run deploy.yml -f environment=staging
Passes a workflow input named environment.
On a branch
gh workflow run ci.yml --ref feature/login
Runs the workflow using that branch’s workflow file and code.
Common mistakes
- Trying to dispatch a workflow that lacks `workflow_dispatch`.
- Passing inputs that are not declared in the workflow YAML.
Related commands
- gh workflow listList GitHub Actions workflows defined in the repository.
- gh run listList recent GitHub Actions workflow runs for the repository.
- gh run watchWatch a GitHub Actions run until it completes, printing progress updates.
- gh run viewInspect a GitHub Actions run, including jobs, annotations, and optional logs.
- gh auth loginAuthenticate the GitHub CLI with GitHub.com or GitHub Enterprise so other gh commands can run.
- gh pr createCreate a pull request from the current branch with title, body, reviewers, and base branch options.
- gh pr mergeMerge a pull request using merge commit, squash, or rebase strategies.
- gitTrack source history and collaborate through distributed repositories.
FAQ
What does gh workflow run do in GitHub CLI?
Trigger a workflow_dispatch event for a GitHub Actions workflow.
Does gh workflow run work on Windows and Linux?
Yes. The GitHub CLI (`gh`) runs on Linux, Windows, and macOS with the same subcommand syntax after you authenticate with `gh auth login`.
What is a practical gh workflow run example?
Try `gh workflow run ci.yml` — Starts the workflow defined in .github/workflows/ci.yml when it supports dispatch.
Do I need a token in the command line for gh workflow run?
Prefer `gh auth login` so credentials stay in the system keyring or secure storage. Avoid pasting personal access tokens into shell history.
Browse the full Linux and Windows command reference to search more bash, CMD, PowerShell, Conda, and GitHub CLI commands.