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_dispatch workflows. 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_dispatch and repository_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 and required.
  • Limits: up to 25 top-level input properties and 65,535 characters of input payload.
  • Inputs arrive in the inputs context (booleans stay booleans) and in github.event.inputs.
  • GITHUB_REF is 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 in github.event.client_payload.
  • It always runs on the default branch (GITHUB_REF is the default branch); there's no ref parameter.
  • Inputs are not typed or validated by GitHub; your workflow has to check them.
on:
  repository_dispatch:
    types: [content_published]

Side by side

Side by side
workflow_dispatchrepository_dispatch
TargetsOne workflow fileEvery workflow listening for the event_type
BranchAny branch or tag via refDefault branch only
DataTyped inputs (≤25 top-level, ≤65,535 chars)Free-form client_payload (≤10 top-level, ≤65,535 chars)
UI buttonYes (web and GitHub Mobile)No
REST endpointPOST /repos/{o}/{r}/actions/workflows/{id}/dispatchesPOST /repos/{o}/{r}/dispatches
Classic PATrepo scoperepo scope
Fine-grained PATActions: writeContents: write
Typical useManual runs, deploys with options, ops buttonsWebhooks 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_run is a real boolean in the workflow. The github.event.inputs copy keeps them as strings, which is a common source of if: bugs. Prefer inputs.*.
  • Inputs you leave out get their default from 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

Errors, decoded
ResponseEventMeaning and fix
404 Not FoundbothToken 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' triggerworkflow_dispatchThe file at ref lacks the trigger. Merge it to that branch
422 No ref found for: ...workflow_dispatchBranch or tag in ref doesn't exist
422 Unexpected inputs providedworkflow_dispatchAn input key isn't declared in the YAML
422 Required input '...' not providedworkflow_dispatchAdd the input, or give it a default
204 but nothing runsrepository_dispatchevent_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 integrationchainingGITHUB_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 a run: script. Pass them through env: as in the examples, which GitHub recommends to avoid script injection (secure use reference).
  • Validate free-form payloads. repository_dispatch accepts 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) for workflow_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:

  1. 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.
  2. Is another system starting it, and do several workflows need to react? Use repository_dispatch, with one event_type that several workflows listen for.
  3. Does it have to run code from a branch other than the default? Only workflow_dispatch takes a ref.
  4. Do you want the run URL back from the API call? Per the current docs, workflow_dispatch returns it. With repository_dispatch you have to look the run up afterwards.
  5. 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_dispatch with event_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_dispatch must 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.

Last checked: 2026-11-01 (GitHub Docs: events that trigger workflows, REST workflows and repositories, fine-grained permissions; GitHub CLI manual).