GitHub event triggers
Start a session when a pull request, issue, comment, check suite, or workflow run event arrives for one repository, filtered by conditions.
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.
Team ownership and repository grants
An event run keeps the automation's saved owning team, or workspace ownership. It does not use the triggering sender's memberships to choose a team. That routing is specific to direct GitHub mentions.
Matching uses GitHub's numeric repository ID, not just its owner/name. A rename preserves identity, and the run uses the current owner and repository name from the event. Each candidate is checked again before admission for its enabled state, event type, conditions, and exactly one matching repository.
A team-owned automation needs a current repository or installation grant covering that ID. Grant coverage is checked during admission and launch; revocation prevents a run even if its conditions match. Restoring the grant allows later events, but does not replay skipped events. Normal automation execution authorization also applies; a valid webhook or an Actor condition is not itself a repository grant.
A matching event denied for missing grant coverage is recorded as an unauthorized run with reason repo_not_granted, without creating a session.
For team-owned automatic reviews, use a GitHub Event automation. The integration setting Auto-review new PRs is a separate, deprecated workspace-owned review-on-open path and does not use team mention routing. It is not disabled merely because it is deprecated.
The runtime default for TEAMS_ENFORCEMENT remains shadow, not on. These automation admission checks do not imply full team-read isolation for the resulting session.
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:
| Event Type | Fires when | Conditions offered |
|---|---|---|
| PR Opened | A pull request was opened | Head branch, Target branch, Label, Actor, Draft |
| PR Updated | New commits were pushed to a pull request | Head branch, Target branch, Label, Actor, Draft |
| PR Ready for Review | A draft pull request was marked ready for review | Head branch, Target branch, Label, Actor |
| PR Closed | A pull request was closed or merged | Head branch, Target branch, Label, Actor |
| Issue Comment | A comment was added to an issue or PR | Actor |
| Review Comment | A review comment was added to a pull request | Head branch, Target branch, Actor |
| Check Suite Completed | A CI check suite finished running | Head branch, Actor, Conclusion |
| Workflow Run Completed | A GitHub Actions workflow run finished | Head branch, Actor, Conclusion, Workflow Name |
| Issue Opened | A new issue was opened | Label, Actor |
| Issue Labeled | A label was added to an issue | Label, Actor |
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.
| Condition | How it matches |
|---|---|
| Head branch | The PR source branch (or the branch of a check suite or workflow run) matches one of the listed patterns. Globs such as feature/* are supported. |
| Target branch | The PR merge base matches one of the listed patterns (PR and review-comment events only). |
| Label | any of: at least one listed label is on the PR or issue. none of: no listed label is on it. Matching ignores case. |
| Actor | The GitHub login that triggered the event is in the list (include) or not in the list (exclude); matching ignores case. |
| Conclusion | Equals the chosen value. |
| Workflow Name | Equals the workflow name exactly, for example CI. |
| Draft | Not draft skips draft pull requests, Draft only skips the rest. |
Every list-type condition needs at least one entry; an empty one blocks saving.
A pull request that an automation run's own prompt opened is authored by the GitHub App, so its PR Opened event has the App bot login (for example my-app[bot]) as actor. An Actor condition that names the automation's executor does not match that event.
Draft pull requests
Add Draft set to Not draft to PR Opened and PR Updated automations to skip draft pull requests. Open-Inspect checks the condition before it starts a session, so a skipped draft costs nothing. Add a PR Ready for Review automation with the same instructions so the pull request still gets a run when the author marks it ready without a new push.
Skip pull requests by label
Add Label set to none of to keep an automation off pull requests that carry a given label, for example dependencies or a translation bot's label. A pull request or issue with no labels passes a none of condition and fails an any of condition.
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, orskipped.
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:
| Event | Context |
|---|---|
| Pull request events | PR number and title, author, head and base branch, merged or closed status, labels, and the first 500 characters of the description |
| Issue events | Issue number and title, author, labels, and the first 500 characters of the body |
| Issue Comment | Issue or PR number and title, commenter, and the first 500 characters of the comment |
| Review Comment | PR number and title, reviewer, file path, the first 500 characters of the comment, and up to 1,000 characters of the diff hunk |
| Check Suite Completed | Conclusion, branch, commit, attached pull requests |
| Workflow Run Completed | Workflow name, run id, conclusion, workflow file, branch, commit, run URL |
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:
| Event | Concurrency scope | Deduplication |
|---|---|---|
| Pull request events | Per PR number | Per PR, action, and head commit |
| Issue events | Per issue number | Per issue and action |
| Issue Comment | Per comment | Per comment |
| Review Comment | Per PR number | Per comment |
| Check Suite Completed | Per check suite | Per check suite |
| Workflow Run Completed | Per workflow run | Per run attempt |
A second event that lands in an active concurrency scope is skipped rather than queued.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Events never start a run | The GitHub App is not subscribed to the event, lacks the permission, or the webhook worker is not deployed | Ask an operator to complete the GitHub bot setup; see GitHub integration |
| The form will not save | No event type selected, or a list condition is empty | Select an Event Type; give every condition at least one value |
| A condition disappeared after changing the event type | The new event type cannot answer it | Expected; the form lists what was removed |
| Workflow runs fire on success and failure | No Conclusion condition | Add Conclusion set to failure |
| A rerun did not fire | It was a redelivery of the same attempt, or the run's concurrency scope was still active | Rerun the workflow so GitHub sends a new attempt |
Next steps
Inbound webhooks
Trigger an automation from any system with an authenticated JSON POST, filter payloads with JSONPath conditions, and deduplicate retries.
Slack message triggers
Start a session when a matching message is posted in a watched Slack channel, reply in the thread, and continue the session from thread replies.