workflow_dispatch vs repository_dispatch vs REST API vs gh CLI: How to Trigger GitHub Actions
Disclosure: I build Pocket Actions, an iPhone app that triggers
workflow_dispatchworkflows. Most of this post is about GitHub's own mechanisms, which apply whatever client you use. All limits and permissions below come from GitHub Docs (linked) as of the last-checked date.
Two events, many ways to send them
People often compare "workflow_dispatch vs repository_dispatch vs the API vs gh CLI" as if they were four alternatives. They're really two layers:
- Events your workflow listens for:
workflow_dispatchandrepository_dispatch. - Clients that send those events: the GitHub web UI, GitHub Mobile, the REST API (curl, scripts, iOS Shortcuts, other apps), and the GitHub CLI.
Pick the event first, then the client.
The two events
workflow_dispatch — "run this workflow"
From the events reference:
- You target one specific workflow file.
- The workflow file must exist on the default branch; the web UI shows a "Run workflow" button then.
- You can pass a
ref(branch or tag) and typed inputs:string,boolean,choice,environment(and more), with defaults andrequired. - Limits: up to 25 top-level input properties and 65,535 characters of input payload.
- Inputs arrive in the
inputscontext (booleans stay booleans) and ingithub.event.inputs. GITHUB_REFis the branch or tag you dispatched to.
on:
workflow_dispatch:
inputs:
environment:
type: choice
options: [staging, production]
required: true
repository_dispatch — "something happened, react to it"
From the events reference:
- You send an event to the repository, with a custom
event_type(max 100 characters). Every workflow listening for that type runs — potentially several. - Extra data goes in
client_payload: max 10 top-level properties, 65,535 characters. It appears ingithub.event.client_payload. - It always runs on the default branch (
GITHUB_REFis the default branch); there's norefparameter. - Inputs are not typed or validated by GitHub; your workflow has to check them.
on:
repository_dispatch:
types: [content_published]
Side by side
Scroll sideways to see the whole table
workflow_dispatch | repository_dispatch | |
|---|---|---|
| Targets | One workflow file | Every workflow listening for the event_type |
| Branch | Any branch or tag via ref | Default branch only |
| Data | Typed inputs (≤25 top-level, ≤65,535 chars) | Free-form client_payload (≤10 top-level, ≤65,535 chars) |
| UI button | Yes (web and GitHub Mobile) | No |
| REST endpoint | POST /repos/{o}/{r}/actions/workflows/{id}/dispatches | POST /repos/{o}/{r}/dispatches |
| Classic PAT | repo scope | repo scope |
| Fine-grained PAT | Actions: write | Contents: write |
| Typical use | Manual runs, deploys with options, ops buttons | Webhooks from CMS/other services, fan-out to several workflows |
Permission sources: workflows REST, repository dispatch REST, fine-grained permissions table.
One more detail worth knowing: when a workflow uses GITHUB_TOKEN to create events, most of those events don't start new runs — workflow_dispatch and repository_dispatch are the exceptions (events reference). That's what makes them useful for chaining workflows.
The clients
REST API (curl, scripts, Shortcuts, apps)
curl -L -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/vnd.github+json" \
https://api.github.com/repos/OWNER/REPO/actions/workflows/deploy.yml/dispatches \
-d '{"ref":"main","inputs":{"environment":"staging"}}'
The workflow dispatch endpoint accepts the workflow ID or the file name. Per GitHub's current REST docs, a successful workflow dispatch returns 200 with workflow_run_id, run_url and html_url (docs). Whether older API versions still return an empty 204 is unconfirmed, so treat any 2xx as success. A client can link straight to the run.
Anything that can make an HTTP request is a client: a cron job on a server, a Zapier/Make/n8n webhook step, an iOS Shortcut, another workflow.
GitHub CLI: gh workflow run
From the manual:
gh workflow run deploy.yml --ref my-branch -f environment=staging
echo '{"environment":"staging"}' | gh workflow run deploy.yml --json
gh workflow run # interactive: pick a workflow, answer prompts
gh creates a workflow_dispatch event only. For repository_dispatch, use gh api against the REST endpoint. It's the nicest option at a terminal, and it handles auth for you — GitHub suggests the CLI over hand-made PATs for command-line use (PAT docs).
Web UI and GitHub Mobile
The "Run workflow" button appears for workflow_dispatch workflows on the default branch. GitHub Mobile has supported it since July 2024 (changelog). No UI exists for repository_dispatch.
Third-party phone apps
Several iPhone apps send workflow_dispatch for you (comparison). Pocket Actions is one: it reads your workflow's inputs, builds a form, and sends the dispatch in 1–3 taps. Its limits, stated plainly:
- it always dispatches to
main(no branch choice); - it doesn't show run results or logs;
- it doesn't send
repository_dispatch; - it's iOS only (Android in closed testing);
- free use is 5 runs a day / 17 a week (Premium $2.99/mo or $49.99 lifetime).
Working examples for both events
The tables above show the rules. The examples below show what the files and calls look like, from sending the event to reading its data in the workflow.
workflow_dispatch: sender and receiver
Receiver:
# .github/workflows/deploy.yml
name: Deploy
on:
workflow_dispatch:
inputs:
environment:
type: choice
options: [staging, production]
required: true
dry_run:
type: boolean
default: true
version:
type: string
required: false
jobs:
deploy:
runs-on: ubuntu-latest
environment: ${{ inputs.environment }}
steps:
- uses: actions/checkout@v4
- name: Show what we got
env:
ENVIRONMENT: ${{ inputs.environment }}
DRY_RUN: ${{ inputs.dry_run }}
VERSION: ${{ inputs.version }}
run: |
echo "env=$ENVIRONMENT dry_run=$DRY_RUN version=${VERSION:-latest} ref=$GITHUB_REF"
- if: ${{ !inputs.dry_run }}
run: ./deploy.sh
Senders, all equivalent:
# REST
curl -L -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/vnd.github+json" \
https://api.github.com/repos/OWNER/REPO/actions/workflows/deploy.yml/dispatches \
-d '{"ref":"main","inputs":{"environment":"staging","dry_run":"false","version":"1.4.2"}}'
# gh CLI
gh workflow run deploy.yml --ref main -f environment=staging -f dry_run=false -f version=1.4.2
Two details:
- Over REST, send input values as JSON strings ("false", not false). GitHub converts them to the declared type, so
inputs.dry_runis a real boolean in the workflow. Thegithub.event.inputscopy keeps them as strings, which is a common source ofif:bugs. Preferinputs.*. - Inputs you leave out get their
defaultfrom the YAML.
repository_dispatch: sender and receiver
Receiver:
# .github/workflows/on-publish.yml
name: On publish
on:
repository_dispatch:
types: [content_published, content_deleted]
jobs:
rebuild:
runs-on: ubuntu-latest
steps:
- name: Validate payload
env:
EVENT: ${{ github.event.action }}
SLUG: ${{ github.event.client_payload.slug }}
run: |
if [ -z "$SLUG" ]; then echo "missing slug" >&2; exit 1; fi
case "$SLUG" in *[!a-z0-9-]*) echo "bad slug" >&2; exit 1;; esac
echo "event=$EVENT slug=$SLUG"
- uses: actions/checkout@v4
- run: npm ci && npm run build
Sender:
curl -L -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/vnd.github+json" \
https://api.github.com/repos/OWNER/REPO/dispatches \
-d '{"event_type":"content_published","client_payload":{"slug":"hello-world"}}'
# same thing with gh
gh api repos/OWNER/REPO/dispatches \
-f event_type=content_published \
-f 'client_payload[slug]=hello-world'
The event_type you send shows up as github.event.action in the workflow. A successful repository dispatch returns 204 No Content (REST docs), so unlike the current workflow dispatch response, you don't get a run URL back. And because client_payload isn't typed or validated, the workflow above checks it before using it.
Chaining: one workflow starting another
Because workflow_dispatch and repository_dispatch are exceptions to the "GITHUB_TOKEN events don't start runs" rule, a workflow can start another workflow in the same repository without a PAT:
jobs:
build:
runs-on: ubuntu-latest
permissions:
actions: write # needed to create a workflow_dispatch event
steps:
- run: echo "build done"
- env:
GH_TOKEN: ${{ github.token }}
run: gh workflow run deploy.yml --repo "$GITHUB_REPOSITORY" --ref main -f environment=staging
The permissions block gives GITHUB_TOKEN only what it needs (GITHUB_TOKEN permissions). To send repository_dispatch with GITHUB_TOKEN instead, the permission is contents: write. To reach a different repository, GITHUB_TOKEN won't do; you need a PAT or a GitHub App token for that repository.
Errors, decoded
Scroll sideways to see the whole table
| Response | Event | Meaning and fix |
|---|---|---|
404 Not Found | both | Token can't see the repo, or the path or workflow file name is wrong. GitHub returns 404 instead of 403 for private resources (troubleshooting) |
422 Workflow does not have 'workflow_dispatch' trigger | workflow_dispatch | The file at ref lacks the trigger. Merge it to that branch |
422 No ref found for: ... | workflow_dispatch | Branch or tag in ref doesn't exist |
422 Unexpected inputs provided | workflow_dispatch | An input key isn't declared in the YAML |
422 Required input '...' not provided | workflow_dispatch | Add the input, or give it a default |
| 204 but nothing runs | repository_dispatch | event_type doesn't match any types: entry on the default branch, or the listening workflow isn't on the default branch yet |
403 Resource not accessible by integration | chaining | GITHUB_TOKEN lacks actions: write / contents: write; add a permissions block |
(Status codes come from GitHub's REST docs; the quoted message texts are typical wording and unconfirmed, since GitHub doesn't document them. The cause column is what to check.)
When a call returns success but you can't find the run, look at the Actions tab filtered by the workflow name, and check the event column. Dispatched runs are labeled with the event that started them, which quickly tells you whether the run was created at all or just failed early.
Security notes for both events
- Treat inputs and payloads as untrusted text. Don't drop
${{ inputs.x }}or${{ github.event.client_payload.x }}straight into arun:script. Pass them throughenv:as in the examples, which GitHub recommends to avoid script injection (secure use reference). - Validate free-form payloads.
repository_dispatchaccepts any JSON from anyone holding a token with Contents: write. Check shapes and allowed characters. - Scope the sender's token. A webhook from a CMS needs only Contents: write on one repository for
repository_dispatch. A phone button needs only Actions: write (plus whatever reads the app does) forworkflow_dispatch. - Gate production with environments. Either event can start a deploy; required reviewers on the environment make it wait for a human (environments).
A quick decision walk-through
Ask these in order:
- Is a person starting it? Use
workflow_dispatch. You get a button in the web UI and GitHub Mobile, typed inputs, and a form generated for you. - Is another system starting it, and do several workflows need to react? Use
repository_dispatch, with oneevent_typethat several workflows listen for. - Does it have to run code from a branch other than the default? Only
workflow_dispatchtakes aref. - Do you want the run URL back from the API call? Per the current docs,
workflow_dispatchreturns it. Withrepository_dispatchyou have to look the run up afterwards. - Is the sender a third-party webhook you can't customize? You may need a small relay (a serverless function, a Make/Zapier/n8n step) that turns its payload into either call.
If two answers point in different directions, you can support both. A workflow can list workflow_dispatch and repository_dispatch under on:, and read inputs or client_payload depending on github.event_name.
A small example of that pattern, with values passed through env: as recommended above:
- env:
TARGET: ${{ github.event_name == 'workflow_dispatch' && inputs.environment || github.event.client_payload.environment }}
run: echo "deploying to $TARGET"
Which should you use?
- A person clicking "run" — deploys, reports, maintenance:
workflow_dispatch. Typed inputs, a UI button, any branch. - An external system announcing an event, possibly to several workflows:
repository_dispatchwithevent_type. - From a terminal:
gh workflow run. - From a script or service: the REST endpoint with a fine-grained PAT (Actions: write for workflow dispatch, Contents: write for repository dispatch), limited to one repository with an expiry.
- From a phone: GitHub Mobile, an iOS Shortcut calling the REST API, or an app like Pocket Actions — see 7 ways to trigger GitHub Actions from iPhone.
Common pitfalls
- The button doesn't appear: the workflow file with
workflow_dispatchmust be on the default branch. - repository_dispatch didn't run my branch's changes: it always uses the default branch.
- Too many inputs: workflow_dispatch caps top-level inputs at 25; group values into a JSON string if needed.
- 403 with a fine-grained token: check you granted Actions: write (workflow dispatch) or Contents: write (repository dispatch) on that specific repository.
A real example
I keep an "evaluate this stock with AI" automation as a workflow_dispatch workflow and run it from my phone with Pocket Actions only when I need it, instead of on a schedule.
Try it
If your workflows already have workflow_dispatch, you can try triggering them from iPhone free (5 runs a day).
View Pocket Actions on the App Store
FAQ
What's the difference between workflow_dispatch and repository_dispatch? workflow_dispatch runs one specific workflow with typed inputs on a branch you choose. repository_dispatch sends a custom event to the repository; every workflow listening for that event_type runs on the default branch with a free-form client_payload.
Can I choose the branch with repository_dispatch? No. It runs on the default branch. Use workflow_dispatch with ref if you need a branch.
How do I pass inputs with gh workflow run? Use -f key=value (or -F), or pipe JSON with --json. Add --ref to pick a branch.
What token permissions do I need? Classic PATs need the repo scope for both. Fine-grained PATs need Actions: write for workflow dispatch and Contents: write for repository dispatch.
Can a workflow trigger another workflow? Yes. Events created with GITHUB_TOKEN generally don't start new runs, but workflow_dispatch and repository_dispatch are exceptions.
Related
- How to Trigger GitHub Actions from Your iPhone: 7 Options Compared
- GitHub Actions iPhone apps compared
- iOS Shortcuts for GitHub Actions: DIY vs a dedicated app
- Pocket Actions changelog
Last checked: 2026-11-01 (GitHub Docs: events that trigger workflows, REST workflows and repositories, fine-grained permissions; GitHub CLI manual).
