repository_dispatch is a GitHub Actions trigger that starts a workflow when an outside system calls the repository dispatch API with a custom event type. Use it when something that is not a Git event, such as an advisory feed or ticket update, should start a security job.
How it works
Most workflow triggers react to things that happen inside GitHub: a push, a pull request, a schedule. Security work often starts elsewhere. A new advisory lands, a vendor sends a notice, or someone approves a ticket. For those cases GitHub provides a custom event.
You send a request to the repository dispatch endpoint with an event_type and an optional client_payload. The workflow lists the types it accepts:
on:
repository_dispatch:
types: [advisory_published]
GitHub's event reference states a few hard limits. The workflow file must exist on the default branch for the event to trigger a run, and the run uses the last commit on the default branch. The event_type is limited to 100 characters. The payload can have at most 10 top-level properties. The reference also notes the payload can hold at most 65,535 characters, so keep it to identifiers and links, never whole documents.
Good uses
- A webhook receiver gets an advisory notification and dispatches a targeted rescan of the affected repositories. See how to build a webhook endpoint that triggers security scans.
- A ticketing system approves an exception and dispatches a workflow that records it.
- A scheduled job in another system starts a report in this repository.
Treat the payload as untrusted input
Anyone or anything that can call the endpoint can set the payload, so read it like user input. Pass it through an environment variable, never inline in a shell command. GitHub's example does exactly this with an env block and then echoes the variable. Validate that package names, versions and repository names match expected patterns before you act on them. Our post on script injection in automation workflows explains why.
Also think about who holds the token that calls the API. It needs write access to the repository, so use a narrowly scoped credential, keep it in the sender's secret store, and rotate it on a schedule.
repository_dispatch versus workflow_dispatch
| repository_dispatch | workflow_dispatch | |
|---|---|---|
| Started by | An API call with an event type | A person or an API call for one named workflow |
| Inputs | Free form client payload | Declared inputs with types |
| Best for | Events from outside systems | Manual runs and on demand reports |
| Runs on | Default branch | A branch you choose |
If a human clicks a button, prefer workflow_dispatch because the inputs are declared and validated by the UI. If a machine sends the event, repository_dispatch is the fit.
One more detail: recursion
GitHub's documentation says that events triggered by the repository's GITHUB_TOKEN do not create new workflow runs, with the exception of workflow_dispatch and repository_dispatch. That exception is useful and slightly dangerous. A workflow that dispatches itself can loop. Add a counter or a guard condition in the payload and cap the chain. See also why a bot commit did not trigger CI.
Quick check
Can repository_dispatch run a workflow on a feature branch?
No. It runs the workflow file on the default branch, so test changes by merging them or by using workflow_dispatch on a branch.
Is it safe to pass a package name from the payload into a script?
Only after validating it and passing it through an environment variable. Never paste payload values directly into shell code.
Sources
Safeguard's continuous monitoring and policy gates can be one of the senders that tells your pipeline something changed. Try the free scan at gold.safeguard.sh/scan.
Last reviewed: 19 October 2026.
