Skip to content

Commit adb3505

Browse files
gregbergegregberge
committed
Document repository_dispatch events
1 parent b6cf487 commit adb3505

2 files changed

Lines changed: 330 additions & 0 deletions

File tree

‎docs/learn/integrations/github-repository-dispatch.mdx‎

Lines changed: 317 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,317 @@
1+
---
2+
slug: /github-repository-dispatch
3+
sidebar_label: GitHub repository dispatch
4+
sidebar_position: 13
5+
description: Trigger GitHub Actions workflows on Argos build and deployment events using repository_dispatch — with the full event payload available to your workflow.
6+
---
7+
8+
# GitHub repository dispatch events
9+
10+
Argos sends [`repository_dispatch` events](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#repository_dispatch) to GitHub whenever a build or deployment changes state. These events can trigger GitHub Actions workflows, enabling continuous integration tasks that depend on Argos results — running end-to-end tests after a successful preview deployment, kicking off a downstream pipeline once visual diffs are accepted, posting to an internal system when a regression is detected, and so on.
11+
12+
Each event carries a rich JSON payload describing the build or deployment, accessible in your workflow as `github.event.client_payload`.
13+
14+
## Availability
15+
16+
Repository dispatch events are sent **only when the repository is connected through the main [Argos GitHub App](/github)**.
17+
18+
The "GitHub without content access" app does not have the `contents: write` permission required by the [GitHub repository dispatch API](https://docs.github.com/en/rest/repos/repos#create-a-repository-dispatch-event), so no events are emitted for repositories installed with that limited app. If you rely on `repository_dispatch` events, install the main Argos GitHub App. See [Choose your access level](/github#choose-your-access-level).
19+
20+
| Argos GitHub App | Repository dispatch events |
21+
| ------------------------------------ | -------------------------- |
22+
| Main app (full access) | Emitted |
23+
| Without content access (limited app) | Not emitted |
24+
25+
## Why use `repository_dispatch`
26+
27+
- **Trigger on real Argos state.** Run a job when a build is `diff-accepted`, when a deployment is `success`, or when a diff is `rejected` — not just on a generic check-completed signal.
28+
- **Rich payload.** Build number, status, conclusion, commit, branch, base branch, PR number, build URL, project information are all included. No follow-up API call needed to figure out what happened.
29+
- **Decoupled workflows.** Your post-build automation lives in a workflow file, not in a separate webhook handler. Triggering jobs is just a YAML `on:` entry.
30+
31+
:::tip
32+
33+
`repository_dispatch` only triggers a workflow run if the workflow file exists on the **default branch** (for example `main`). To test a workflow before merging, add a [`workflow_dispatch` trigger](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch) so you can run it manually from any branch.
34+
35+
:::
36+
37+
## Event types
38+
39+
Argos emits two families of events: **build events** and **deployment events**. The dispatch `event_type` is always of the form `argos.<resource>.<action>`.
40+
41+
### Build events
42+
43+
Build events fire on every state change of an Argos build.
44+
45+
```yaml
46+
on:
47+
repository_dispatch:
48+
types:
49+
# Build has been received and queued for processing.
50+
- "argos.build.queued"
51+
# Build is being processed (screenshots being compared).
52+
- "argos.build.progress"
53+
# Build completed with no visual differences against the baseline.
54+
- "argos.build.no-diff-detected"
55+
# Build completed and visual differences were detected — waiting for review.
56+
- "argos.build.diff-detected"
57+
# A reviewer accepted the visual differences.
58+
- "argos.build.diff-accepted"
59+
# A reviewer rejected the visual differences.
60+
- "argos.build.diff-rejected"
61+
```
62+
63+
### Deployment events
64+
65+
Deployment events fire when an Argos deployment is created or completes successfully. Deployments represent a preview or production environment tracked by Argos (for example, a Vercel preview).
66+
67+
```yaml
68+
on:
69+
repository_dispatch:
70+
types:
71+
# Deployment has been registered and is being processed.
72+
- "argos.deployment.progress"
73+
# Deployment is live and ready (preview URL is reachable).
74+
- "argos.deployment.success"
75+
```
76+
77+
## Payloads
78+
79+
Every event has the same top-level shape:
80+
81+
```json
82+
{
83+
"event_type": "argos.build.diff-detected",
84+
"client_payload": {
85+
"argos": {
86+
/* event-specific fields */
87+
}
88+
}
89+
}
90+
```
91+
92+
In GitHub Actions, the payload is exposed under `github.event.client_payload`. The Argos-specific fields are nested under `client_payload.argos` so future top-level metadata can be added without breaking existing workflows.
93+
94+
### Build event payload
95+
96+
```json title="github.event.client_payload"
97+
{
98+
"argos": {
99+
"type": "build",
100+
"action": "diff-detected",
101+
"build": {
102+
"id": "01H8X9Y2ZQABCDEFGHJKMNPQRS",
103+
"number": 42,
104+
"name": "default",
105+
"type": "check",
106+
"status": "diff-detected",
107+
"conclusion": "changes-detected",
108+
"url": "https://app.argos-ci.com/my-team/my-project/builds/42",
109+
"commit": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
110+
"branch": "feature/login",
111+
"baseCommit": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
112+
"baseBranch": "main",
113+
"prNumber": 123,
114+
"prHeadCommit": "cccccccccccccccccccccccccccccccccccccccc"
115+
},
116+
"project": {
117+
"id": "01H8X9Y2ZQ0000000000000000",
118+
"name": "my-project",
119+
"url": "https://app.argos-ci.com/my-team/my-project"
120+
}
121+
}
122+
}
123+
```
124+
125+
#### `argos.build` fields
126+
127+
| Field | Type | Description |
128+
| -------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
129+
| `id` | `string` | Unique identifier of the build. |
130+
| `number` | `number` | Sequential build number scoped to the project. Matches the number shown in the Argos UI. |
131+
| `name` | `string` | Build name used to group screenshots (defaults to `default`). Useful when a project produces multiple parallel builds. |
132+
| `type` | `"reference" \| "check" \| "orphan" \| "skipped" \| null` | Whether the build is a baseline (`reference`), a comparison build (`check`), has no baseline available (`orphan`), or was skipped. |
133+
| `status` | `string` | Same as the `action` field — the notification type that triggered the dispatch (`queued`, `progress`, `no-diff-detected`, `diff-detected`, `diff-accepted`, `diff-rejected`). |
134+
| `conclusion` | `"no-changes" \| "changes-detected" \| null` | Final outcome once the build has been processed. `null` while the build is still in progress. |
135+
| `url` | `string` | Direct link to the build in Argos. |
136+
| `commit` | `string` | SHA of the commit the build was uploaded for. |
137+
| `branch` | `string \| null` | Branch the build belongs to. |
138+
| `baseCommit` | `string \| null` | SHA of the baseline commit Argos compared against. |
139+
| `baseBranch` | `string \| null` | Branch of the baseline build. Usually the project's reference branch (for example `main`). |
140+
| `prNumber` | `number \| null` | Pull request number associated with the build, when applicable. |
141+
| `prHeadCommit` | `string \| null` | SHA of the pull request's head commit. Differs from `commit` when the build was uploaded from a merge commit (for example inside a merge queue). |
142+
143+
#### `argos.project` fields
144+
145+
| Field | Type | Description |
146+
| ------ | -------- | ------------------------------------ |
147+
| `id` | `string` | Argos project identifier. |
148+
| `name` | `string` | Project name. |
149+
| `url` | `string` | Direct link to the project in Argos. |
150+
151+
### Deployment event payload
152+
153+
```json title="github.event.client_payload"
154+
{
155+
"argos": {
156+
"type": "deployment",
157+
"action": "success",
158+
"deployment": {
159+
"id": "01H8X9Y2ZQABCDEFGHJKMNPQRS",
160+
"status": "ready",
161+
"url": "https://my-app-pr-123.preview.example.com",
162+
"environment": "preview",
163+
"branch": "feature/login",
164+
"commit": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
165+
"prNumber": 123
166+
},
167+
"project": {
168+
"id": "01H8X9Y2ZQ0000000000000000",
169+
"name": "my-project"
170+
}
171+
}
172+
}
173+
```
174+
175+
#### `argos.deployment` fields
176+
177+
| Field | Type | Description |
178+
| ------------- | --------------------------------- | ------------------------------------------------------------------------------------------------- |
179+
| `id` | `string` | Unique identifier of the deployment. |
180+
| `status` | `"pending" \| "ready" \| "error"` | Lifecycle state of the deployment. `ready` means the URL is reachable. |
181+
| `url` | `string` | URL of the deployment — the preview URL for `preview` environments, the production URL otherwise. |
182+
| `environment` | `"preview" \| "production"` | Target environment for this deployment. |
183+
| `branch` | `string` | Branch the deployment was built from. |
184+
| `commit` | `string` | Commit SHA the deployment was built from. |
185+
| `prNumber` | `number \| null` | Pull request number associated with the deployment, when applicable. |
186+
187+
#### `argos.project` fields
188+
189+
| Field | Type | Description |
190+
| ------ | -------- | ------------------------- |
191+
| `id` | `string` | Argos project identifier. |
192+
| `name` | `string` | Project name. |
193+
194+
## Examples
195+
196+
### Run end-to-end tests after a successful preview deployment
197+
198+
A common pattern: Argos tracks your preview deployments, and you want to run an end-to-end test suite as soon as the preview is live.
199+
200+
```yaml title=".github/workflows/e2e.yml"
201+
name: End-to-end tests
202+
203+
on:
204+
repository_dispatch:
205+
types:
206+
- "argos.deployment.success"
207+
208+
permissions:
209+
contents: read
210+
pull-requests: read
211+
212+
jobs:
213+
e2e:
214+
runs-on: ubuntu-latest
215+
steps:
216+
- uses: actions/checkout@v6
217+
with:
218+
ref: ${{ github.event.client_payload.argos.deployment.commit }}
219+
220+
- uses: actions/setup-node@v6
221+
222+
- run: npm ci
223+
- run: npx playwright install --with-deps
224+
225+
- name: Run Playwright tests
226+
run: npx playwright test
227+
env:
228+
BASE_URL: ${{ github.event.client_payload.argos.deployment.url }}
229+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
230+
```
231+
232+
### React to a rejected visual review
233+
234+
Block downstream automation as soon as a reviewer rejects a visual diff.
235+
236+
```yaml title=".github/workflows/visual-review.yml"
237+
name: Visual review
238+
239+
on:
240+
repository_dispatch:
241+
types:
242+
- "argos.build.diff-rejected"
243+
- "argos.build.diff-accepted"
244+
245+
jobs:
246+
notify:
247+
runs-on: ubuntu-latest
248+
steps:
249+
- name: Notify on rejection
250+
if: github.event.client_payload.argos.action == 'diff-rejected'
251+
run: |
252+
echo "Build #${{ github.event.client_payload.argos.build.number }} was rejected"
253+
echo "See: ${{ github.event.client_payload.argos.build.url }}"
254+
# Call your incident, Slack, or release-management tooling here.
255+
```
256+
257+
### Trigger only when changes are detected
258+
259+
Listen for `argos.build.diff-detected` to run an automation (a screenshot archive, a downstream design review, etc.) only when there is something to look at.
260+
261+
```yaml title=".github/workflows/visual-diff.yml"
262+
name: Archive visual diffs
263+
264+
on:
265+
repository_dispatch:
266+
types:
267+
- "argos.build.diff-detected"
268+
269+
jobs:
270+
archive:
271+
runs-on: ubuntu-latest
272+
steps:
273+
- name: Archive build
274+
run: |
275+
curl -X POST https://internal.example.com/visual-diffs \
276+
-H "Content-Type: application/json" \
277+
-d '{
278+
"buildId": "${{ github.event.client_payload.argos.build.id }}",
279+
"buildUrl": "${{ github.event.client_payload.argos.build.url }}",
280+
"commit": "${{ github.event.client_payload.argos.build.commit }}",
281+
"pr": ${{ github.event.client_payload.argos.build.prNumber }}
282+
}'
283+
```
284+
285+
## Accessing payload values
286+
287+
In a workflow, the payload is available at `github.event.client_payload`. Argos nests its fields under `argos`:
288+
289+
```yaml
290+
${{ github.event.client_payload.argos.build.url }}
291+
${{ github.event.client_payload.argos.build.commit }}
292+
${{ github.event.client_payload.argos.deployment.url }}
293+
${{ github.event.client_payload.argos.project.name }}
294+
```
295+
296+
You can also filter on the event name itself using the `action` field of the payload — useful when a single workflow subscribes to several event types:
297+
298+
```yaml
299+
jobs:
300+
on-completion:
301+
if: github.event.client_payload.argos.action == 'no-diff-detected'
302+
runs-on: ubuntu-latest
303+
steps:
304+
# ...
305+
```
306+
307+
## Limitations
308+
309+
- `repository_dispatch` events trigger workflow runs only when the workflow file is on the **default branch**. To test a new workflow on a feature branch, add a `workflow_dispatch` trigger and run it manually.
310+
- Repositories installed with the [GitHub app without content access](/github#github-integration-without-content-permission) do **not** receive `repository_dispatch` events — that app lacks the required `contents: write` permission.
311+
- Events are best-effort. If a repository becomes inaccessible (deleted, transferred, renamed, archived, or permissions revoked between the build and the dispatch), Argos drops the event silently rather than failing the build notification.
312+
313+
## See also
314+
315+
- [GitHub integration](/github) — install the main Argos GitHub App.
316+
- [Run on preview deployments](/run-on-preview-deployment) — full end-to-end testing setup with `repository_dispatch`.
317+
- [GitHub: `repository_dispatch` event](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#repository_dispatch) — official GitHub Actions reference.

‎docs/learn/integrations/github.mdx‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ Connect Argos to GitHub for automated visual testing on every pull request and m
1414
- Add commit and pull request checks, so Argos results can block merges when required in GitHub.
1515
- Post [pull request comments](/pull-request-comments) with the latest build results and links back to Argos.
1616
- Analyze commit history to find the right merge base and select the correct [baseline build](/baseline-build) for visual comparisons.
17+
- Emit [`repository_dispatch` events](/github-repository-dispatch) so GitHub Actions workflows can react to Argos build and deployment state changes.
1718

1819
## Why Argos needs repository access
1920

@@ -100,6 +101,18 @@ steps:
100101

101102
Use the pull request numbers included in the merge queue batch. Passing `ARGOS_MERGE_QUEUE_PRS` tells Argos to treat the upload as a merge queue build.
102103

104+
## GitHub Actions automation with repository dispatch
105+
106+
When a repository is connected through the main Argos GitHub App, Argos emits [`repository_dispatch` events](/github-repository-dispatch) to GitHub on every build and deployment state change. You can use these events to trigger GitHub Actions workflows — for example, run end-to-end tests after a successful preview deployment, or call internal tooling when a diff is rejected.
107+
108+
The full list of event types and payload schemas is documented on the [GitHub repository dispatch events](/github-repository-dispatch) page.
109+
110+
:::note
111+
112+
`repository_dispatch` events are only emitted when the repository uses the main Argos GitHub App. The [GitHub app without content access](#github-integration-without-content-permission) lacks the `contents: write` permission required by the GitHub API and does not emit these events.
113+
114+
:::
115+
103116
## GitHub Integration without Content Permission
104117

105118
If you prefer to use Argos without granting full content access to your repositories, you can integrate via a more restricted setup.

0 commit comments

Comments
 (0)