Workflow Orchestration with Repository Dispatch

The GitHub Actions repository_dispatch event allows you to trigger a workflow in a specific repository from external systems or workflows in other repositories via the GitHub API. This enables complex workflow orchestration and automation based on external events (e.g., CMS updates, deployment completion notifications).

What is Repository Dispatch?

repository_dispatch is a GitHub Actions trigger that fires when an HTTP POST request is sent to a GitHub API endpoint.

Key features include:

• Custom Event Types: You can specify an event_type to run only specific workflows.
• Payload Transmission: You can pass data from the trigger source via a client_payload JSON object.

Basic Mechanism

Triggering Side (Sender)

Send a POST request to the GitHub API's Create a repository dispatch event endpoint.

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO/dispatches \
  -d '{"event_type":"my-event-type","client_payload":{"unit":false,"integration":true}}'

Triggered Side (Receiver)

Specify repository_dispatch in the on section of your workflow file, and optionally filter by event type using types.

name: Repository Dispatch Workflow
on:
  repository_dispatch:
    types: [my-event-type]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run script
        run: echo "Received payload: ${{ github.event.client_payload.integration }}"

Use Case: Triggering CD Pipeline from CI Pipeline

In scenarios such as monorepo configurations or when build and deployment repositories are separated, you may want to start CD (deployment) upon the completion of CI (build/test).

Scenario

1. CI Workflow: Builds the application and pushes the Docker image to a registry.
2. CD Workflow: Receives the new image tag information and executes the deployment process.

1. Sender: CI Workflow (ci.yml)

Using the peter-evans/repository-dispatch action makes it easy to send dispatch events.

name: CI Pipeline

on:
  push:
    branches: [ "main" ]

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      # ... Build and Docker image push process ...
      # Assuming image_tag is generated here (e.g., sha-1234567)

      - name: Trigger CD Pipeline
        uses: peter-evans/repository-dispatch@v3
        with:
          token: ${{ secrets.PAT_TOKEN }}
          repository: my-org/my-deploy-repo # Deployment repository (optional if same repo)
          event-type: trigger-deploy
          client-payload: '{"image_tag": "sha-1234567", "environment": "production"}'

info

About Personal Access Tokens (PAT) When triggering other repositories, or if the default GITHUB_TOKEN lacks sufficient permissions (or to prevent recursive triggers), you need to create a PAT with appropriate scopes (usually contents: write or metadata: read) and register it in Secrets.

2. Receiver: CD Workflow (cd.yml)

name: CD Pipeline

on:
  repository_dispatch:
    types: [trigger-deploy]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Deploy Application
        run: |
          echo "Deploying image tag: ${{ github.event.client_payload.image_tag }}"
          echo "Target environment: ${{ github.event.client_payload.environment }}"
          # Actual deployment command (e.g., helm upgrade, kubectl set image, etc.)
          # ./deploy.sh ${{ github.event.client_payload.image_tag }}

Security and Limitations

• Authentication: Write access to the repository is required to send dispatch events.
• Default Branch: The repository_dispatch event is only triggered for workflow files located in the default branch (usually main).
• Rate Limits: GitHub API rate limits apply.

Summary

Repository Dispatch enables flexible workflow orchestration beyond the boundaries of a single GitHub Actions workflow. It is a powerful tool for service-to-service coordination in microservices architectures and event-driven automation from external systems.