Skip to Content
OpenInspect
Automations

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.

Last reviewed View as MarkdownEdit on GitHubGive feedback

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 TypeFires whenConditions offered
PR OpenedA pull request was openedHead branch, Target branch, Label, Actor, Draft
PR UpdatedNew commits were pushed to a pull requestHead branch, Target branch, Label, Actor, Draft
PR Ready for ReviewA draft pull request was marked ready for reviewHead branch, Target branch, Label, Actor
PR ClosedA pull request was closed or mergedHead branch, Target branch, Label, Actor
Issue CommentA comment was added to an issue or PRActor
Review CommentA review comment was added to a pull requestHead branch, Target branch, Actor
Check Suite CompletedA CI check suite finished runningHead branch, Actor, Conclusion
Workflow Run CompletedA GitHub Actions workflow run finishedHead branch, Actor, Conclusion, Workflow Name
Issue OpenedA new issue was openedLabel, Actor
Issue LabeledA label was added to an issueLabel, 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.

ConditionHow it matches
Head branchThe 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 branchThe PR merge base matches one of the listed patterns (PR and review-comment events only).
Labelany of: at least one listed label is on the PR or issue. none of: no listed label is on it. Matching ignores case.
ActorThe GitHub login that triggered the event is in the list (include) or not in the list (exclude); matching ignores case.
ConclusionEquals the chosen value.
Workflow NameEquals the workflow name exactly, for example CI.
DraftNot 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, 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:

EventContext
Pull request eventsPR number and title, author, head and base branch, merged or closed status, labels, and the first 500 characters of the description
Issue eventsIssue number and title, author, labels, and the first 500 characters of the body
Issue CommentIssue or PR number and title, commenter, and the first 500 characters of the comment
Review CommentPR 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 CompletedConclusion, branch, commit, attached pull requests
Workflow Run CompletedWorkflow 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:

EventConcurrency scopeDeduplication
Pull request eventsPer PR numberPer PR, action, and head commit
Issue eventsPer issue numberPer issue and action
Issue CommentPer commentPer comment
Review CommentPer PR numberPer comment
Check Suite CompletedPer check suitePer check suite
Workflow Run CompletedPer workflow runPer run attempt

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

Troubleshooting

SymptomCauseFix
Events never start a runThe GitHub App is not subscribed to the event, lacks the permission, or the webhook worker is not deployedAsk an operator to complete the GitHub bot setup; see GitHub integration
The form will not saveNo event type selected, or a list condition is emptySelect an Event Type; give every condition at least one value
A condition disappeared after changing the event typeThe new event type cannot answer itExpected; the form lists what was removed
Workflow runs fire on success and failureNo Conclusion conditionAdd Conclusion set to failure
A rerun did not fireIt was a redelivery of the same attempt, or the run's concurrency scope was still activeRerun the workflow so GitHub sends a new attempt

Next steps

On this page