Repository Dispatch

~9 min · dispatch, external, webhook

Level 0Apprentice

0 XP0/101 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

External system fires a workflow

repository_dispatch lets external systems trigger a workflow via POST to GitHub's API. The payload is arbitrary JSON, available in github.event.client_payload.

Common uses:

Cross-repo orchestration — repo A finishes a build, fires dispatch in repo B which deploys it.
External CI integration — Jenkins finishes a stage, dispatches to GitHub for the deploy.
Manual triggers from outside GitHub — a Slack slash command, an internal admin tool, a webhook.

The POST

POST /repos/{owner}/{repo}/dispatches
Authorization: Bearer <PAT or App token with contents:write>
Body: {
  "event_type": "deploy-prod",
  "client_payload": { "version": "v1.4.2", "reason": "hotfix" }
}

The workflow listens with on: repository_dispatch: types: [deploy-prod].

Trade-off vs workflow_dispatch

workflow_dispatch — manual UI / gh CLI, typed inputs, requires browser/PAT.
repository_dispatch — programmatic, free-form JSON, suited for machine-to-machine.

Code

Listen for repository_dispatch·yaml

name: external-deploy
on:
  repository_dispatch:
    types: [deploy-prod]

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - name: Show payload
        run: |
          echo "version: ${{ github.event.client_payload.version }}"
          echo "reason: ${{ github.event.client_payload.reason }}"
      - run: ./deploy.sh ${{ github.event.client_payload.version }}

Fire it from a sibling repo's workflow·yaml

      - name: Trigger deploy in other repo
        run: |
          curl -X POST \
            -H 'Accept: application/vnd.github+json' \
            -H "Authorization: Bearer ${{ secrets.CROSS_REPO_PAT }}" \
            https://api.github.com/repos/my-org/deploy-repo/dispatches \
            -d '{"event_type":"deploy-prod","client_payload":{"version":"v1.4.2"}}'

External links

Exercise

Set up a tiny shell script that uses curl to trigger repository_dispatch in a sandbox repo. Have the workflow echo the client_payload. Run the script three times with different payloads and confirm each fires its own run.