Introduction

The repository_dispatch event allows external systems to trigger GitHub Actions workflows via API. When the dispatch payload's event_type does not match the workflow's on.repository_dispatch.types configuration, or the API call is malformed, the workflow does not trigger. This breaks automation pipelines that depend on external event-driven triggers.

Symptoms

  • External system sends repository_dispatch but no workflow runs
  • GitHub API returns 204 No Content (dispatch accepted) but no workflow starts
  • Workflow YAML has wrong event_type configured
  • Payload data not accessible in the workflow via github.event.client_payload
  • Error message: No error -- the dispatch is silently ignored due to event_type mismatch

Common Causes

  • Workflow trigger event_type does not match the API call's event_type parameter
  • API call sent to the wrong repository (typo in owner/repo)
  • Personal access token used for the API call lacks repo scope
  • Workflow file in a branch other than the default branch (dispatch only triggers on default)
  • JSON payload malformed, causing GitHub to reject the event silently

Step-by-Step Fix

  1. 1.Verify the workflow trigger configuration: Check the event_type matches.
  2. 2.```yaml
  3. 3.# .github/workflows/dispatch.yml
  4. 4.on:
  5. 5.repository_dispatch:
  6. 6.types: [deploy-event] # Must match the API event_type exactly
  7. 7.`
  8. 8.Send the dispatch with the correct event_type: Use the GitHub CLI or API.
  9. 9.```bash
  10. 10.# Using GitHub CLI
  11. 11.gh api repos/{owner}/{repo}/dispatches \
  12. 12.--method POST \
  13. 13.-f event_type=deploy-event \
  14. 14.-f 'client_payload={"environment":"production"}'

# Using curl curl -X POST https://api.github.com/repos/{owner}/{repo}/dispatches \ -H "Accept: application/vnd.github.v3+json" \ -H "Authorization: token $GITHUB_TOKEN" \ -d '{"event_type":"deploy-event","client_payload":{"environment":"production"}}' ```

  1. 1.Verify the PAT has the required permissions: Ensure the token can trigger dispatches.
  2. 2.`
  3. 3.# The PAT must have:
  4. 4.# - repo scope (for private repositories)
  5. 5.# - public_repo scope (for public repositories)
  6. 6.# Check token scopes:
  7. 7.curl -s -H "Authorization: token $GITHUB_TOKEN" https://api.github.com | grep -i x-oauth-scopes
  8. 8.`
  9. 9.Check the workflow file is on the default branch: Dispatch events only trigger from the default branch.
  10. 10.```bash
  11. 11.git branch --show-current
  12. 12.# Ensure .github/workflows/dispatch.yml exists on the default branch
  13. 13.gh api repos/{owner}/{repo} --jq '.default_branch'
  14. 14.`
  15. 15.Monitor dispatch events and workflow triggers: Verify the end-to-end flow.
  16. 16.```bash
  17. 17.# Check if the dispatch was received
  18. 18.gh api repos/{owner}/{repo}/actions/runs --jq '.workflow_runs[] | {id, event, status, created_at}'
  19. 19.`

Prevention

  • Document the exact event_type values expected by each workflow in the repository README
  • Include event_type validation in the external system that sends the dispatch
  • Use GitHub CLI for dispatch calls to reduce JSON formatting errors
  • Test repository_dispatch triggers in a staging repository before production use
  • Monitor workflow trigger events with GitHub Actions webhook logging
  • Implement acknowledgment from the triggered workflow back to the dispatching system