Treat the external event as a request to check, not approve
A fictional museum has an off-platform accessibility scanner that finishes checking kiosk pages and wants the GitHub repository to run follow-up tests. The scanner can signal completion, but its callback should not be allowed to publish the site. GitHub Actions supports repository_dispatch for an event created outside GitHub through the REST API. The workflow can examine an event_type and client_payload, then begin a controlled test job. Set the policy first: an incoming event means ‘please verify this artifact,’ never ‘all checks passed.’ Keep deployment in a separate stage gated by trusted branch rules, a validated artifact identity, and the institution’s editorial approval process.
Understand the default-branch execution rule
GitHub’s event reference states that repository_dispatch triggers a workflow only when its workflow file exists on the repository’s default branch. The event’s GITHUB_REF is the default branch, and GITHUB_SHA refers to its latest commit. That behavior is easy to miss if an external scanner was testing a proposed pull-request commit. Do not assume a dispatch event automatically checks that pull request’s exact code. Include a safe candidate identifier, commit SHA, or artifact digest in the event payload, then have the workflow resolve and verify it using appropriate permissions. If the reference is not approved, exit as rejected rather than silently testing whatever commit happens to be current.
Choose a narrow event_type and payload shape
The dispatch request requires an event_type string, and a workflow can limit which custom event types it accepts using the types filter. Give the event a clearly scoped meaning, such as kiosk_accessibility_scan_ready. Pass only nonsecret identifiers in client_payload: a build ID, a digest, a scanner version, and a request correlation ID. The GitHub reference documents limits on event_type length and client_payload size and top-level properties. Validate the current limits before integrating a new scanner. The payload is supplied by an external system and should be treated as untrusted input even if the HTTP request was authenticated to GitHub.
Use an authenticated sender with minimal scope
A trusted automation identity should call the repository dispatch REST endpoint with permissions limited to the required repository and action. Store the credential in a proper secrets manager and rotate it when the sender changes. Do not embed a personal access token in a public kiosk, browser script, or build artifact. Prefer a server-side sender with an auditable request log and rate limits. Record both successful dispatch requests and rejected sends, but do not log the full credential or confidential scanner data. An API acknowledgment says GitHub accepted the event; it does not promise the downstream workflow ran successfully, passed every test, or approved a release.
Validate every field before starting a test job
When the workflow begins, check the allowed event_type, the shape of client_payload, the candidate artifact digest, and whether the candidate belongs to a permitted repository or deployment pipeline. Use environment variables or structured parsing to pass payload values into shell commands; never concatenate untrusted JSON directly into executable shell code. If a field is absent or malformed, fail the workflow with an explicit diagnostic status. Avoid automatic fallbacks to the newest build, because that substitutes a different artifact for the one the external scanner intended. The goal is a traceable correspondence between an external signal and one concrete candidate for further testing.
Separate dispatch, testing, and deployment outcomes
A useful operator view shows three states: external event received, requested artifact tested, and publication authorized. They should never be collapsed into a single green banner. A completed accessibility scan may miss manual keyboard-navigation problems or misidentify visually similar labels. A GitHub test can pass on an approved fixture while the release candidate has changed. Require the final deployment job to verify the artifact digest and consume independent approvals or required checks. If any evidence is missing, keep the museum website unchanged. The external scanner becomes one input into a decision, not the authority that decides whether public-facing visitor guidance can go live.
Defend against duplicate or out-of-order notifications
External systems may retry HTTP requests when a response is lost, so the same logical scan can produce repeated dispatch events. Keep a stable scan identifier and candidate digest, and record which events have already triggered a review. Do not rely on GitHub’s event system to provide a database-level exactly-once business effect. A delayed scan for an older commit should be recognized as stale rather than replacing the newer release’s QA status. Set explicit concurrency and retention rules appropriate to the job, and preserve enough metadata to explain whether a scan was superseded, rejected, or accepted for testing.
Use a least-privilege workflow layout
Keep the receiving workflow read-only where possible. It may download a verified artifact, run checks, and upload a report, but it should not have access to production deployment keys or staff-only editorial systems. If a deployment is needed, make it a separate trusted workflow with documented protected environments and permissions. Evaluate any third-party actions and check that a compromised scanner cannot influence checked-out code or executable commands. The presence of a repository_dispatch event is not proof that the caller’s environment is secure. Treat workflow permissions, input validation, and artifact provenance as independent defenses rather than interchangeable settings.
Rehearse with three synthetic dispatch events
In a staging repository, submit a valid event for a known test build, a malformed event missing the digest, and a correctly shaped but stale event for an older commit. Confirm the first starts only the expected QA path and the other two produce explicit nonapproval outcomes. Inspect the default-branch commit chosen for the workflow and verify that the requested candidate is compared to its trusted artifact source. Record the event ID, test report, and final deployment status as separate values. These are recommended test cases, not claims that this article triggered real GitHub workflows or verified any production museum site.
Publish only from the approved candidate
Before enabling an external trigger in a live release process, document the authorized sender, allowed event types, payload schema, verification method, artifact retention, and retry behavior. Check the status of every required test instead of trusting one ‘pass’ field in the payload. Require an accountable staff member to approve any changes that alter accessibility instructions, event hours, ticket prices, or visitor safety information. If the scanner or GitHub service is unavailable, record the build as pending and preserve the currently approved site. The safe outcome of incomplete automation is a delayed release with clear evidence, not an unreviewed deployment.
How We Research
We reviewed the named official developer references GitHub Docs: Events that trigger workflows, GitHub REST API: Create a repository dispatch event. We compared their documented request and delivery behavior, accepted configuration patterns, and explicit limitations with the proposed hypothetical museum workflow. This article is a source-based implementation guide: we did not execute live customer API calls, inspect private cloud accounts, run production tests, or measure latency, cost, or accuracy. Readers should verify current limits and deployment settings with the original documentation and run their own controlled staging tests before changing public systems.
Frequently Asked Questions
No. The workflow file must exist on the default branch, and the event is associated with the default branch commit.
No. Treat its values as untrusted external input and validate them before any checkout, command, or release decision.
No. It only indicates the event was accepted by the API, not that jobs executed or passed.
The safer design is to let it request tests only. Deployment remains behind required checks and human approval where needed.
Use a stable scan ID and artifact digest, recognize already-reviewed events, and reject stale notifications before a deployment decision.