GitHub event triggers

A GitHub Event automation starts a session when a supported webhook event arrives for its repository and every configured condition passes.

Prerequisites

• The GitHub bot must be deployed and the GitHub App subscribed to the event you want, with the repository permission that event needs. This is an operator task; see GitHub integration.
• The repository must be installed on the GitHub App so it appears in the picker.

The GitHub bot's own scope settings (who may trigger bot workflows, and in which repositories) do not gate automations. Automations are matched separately by repository, event type, enabled state, and conditions.

One repository, one event type

Under Repository Configuration, select exactly one repository. With none selected, the form says "Repository-scoped triggers require exactly one repository". Environments cannot be targeted ("Repository-scoped triggers cannot target environments"), and multi-repository fan-out is not available for event triggers.

Under Event Type, choose one of:

Each event type offers only the conditions its payload can answer. Changing the event type removes conditions the new type cannot answer and the form says which were removed ("Removed Label, not available for this event type."). Paths are never offered: GitHub webhook payloads carry no file list, so there is no path-pattern filtering for any GitHub event.

Conditions

Conditions are optional. When you add any, every condition must pass before a run starts.

Every list-type condition needs at least one entry; an empty one blocks saving.

Workflow Run Completed

Use this event to react to GitHub Actions results. It requires the GitHub App's read-only Actions permission and the Workflow runs event subscription.

• Workflow Name matches the workflow's name exactly.
• Conclusion is one of success (the default), failure, neutral, cancelled, timed_out, action_required, stale, or skipped.

The agent's context block includes the workflow name, conclusion, and run id, plus the workflow file path, branch, short commit SHA, and run URL when GitHub supplies them. Each rerun attempt is deduplicated separately, so a rerun of the same workflow run is admitted once per attempt, while all attempts of one run share a concurrency scope.

Check Suite Completed

Conclusion offers the same values as workflow runs plus startup_failure. Existing automations created with the older Check Conclusion condition keep working; new automations use Conclusion. The context block includes the conclusion, branch, short commit SHA, and the numbers of any pull requests attached to the suite.

What the agent receives

The session prompt is your instructions, then a context block wrapped in a user_context tag, then a guardrail line telling the agent the block is untrusted. The block always names the event and repository, then event-specific facts:

Instructions from the Review new PRs template show the pattern of reading the PR with the GitHub CLI, which is authenticated in the sandbox:

A pull request was opened; its number and details are shown in the event
context. Review it using the GitHub CLI.

1. Read the changes with `gh pr diff <number>`.
2. Assess them for correctness bugs, security issues, missing tests, and
   deviations from the project's conventions.
3. Post your feedback as a review on the existing PR with
   `gh pr review <number> --comment --body "..."`.

Do not open a new pull request; comment on the existing one.

Concurrency and deduplication

Event firings are keyed per event rather than per automation, so unrelated events can run at the same time:

A second event that lands in an active concurrency scope is skipped rather than queued.

Troubleshooting

Next steps

• GitHub integration
• Slack message triggers
• Automation templates