GitHub Events

​

How GitHub events reach your triggers

1. GitHub delivers a webhook for a repository the App is installed on.
2. auto verifies the delivery signature and resolves the installation to your organization’s GitHub connection.
3. The connection resource must subscribe to the raw webhook event name (pull_request, issue_comment, …). Unsubscribed events are dropped at ingress and never reach a trigger.
4. The payload is normalized into a stable shape and stored under an event key like github.pull_request.opened, then routed to every trigger whose event and where match.

triggers:
  - event: github.pull_request.opened
    connection: github-acme
    where:
      $.github.repository.fullName: acme/widgets
    routing:
      kind: spawn

​

Shared payload fields

​

Pull requests

​

github.pull_request.<action>

• $.github.repository.fullName: acme/widgets — scope to one repository
• $.github.pullRequest.merged: true — on closed, distinguish a merge from a plain close
• $.github.author.bot: false — skip bot-opened PRs

name: pr-review
systemPrompt: |
  You are the code reviewer for acme/widgets. You are the one reviewer
  session for your pull request: updates route back to you instead of
  spawning another reviewer. When a new head arrives mid-review, discard
  analysis of the older head and re-review the current head.
  Use upsert_issue_comment for every verdict: create the first comment,
  then edit only your own existing verdict instead of appending another.
  Never use add_issue_comment for verdicts.
initialPrompt: |
  Review pull request #{{github.pullRequest.number}} in
  {{github.repository.fullName}}. Call checks.begin with
  { "name": "pr-review" } before doing anything else, then conclude the
  check with checks.success or checks.failure.
mounts:
  - kind: git
    repository: acme/widgets
    mountPath: /workspace/repo
    ref: refs/pull/{{payload.github.pullRequest.number}}/head
    depth: 1
    auth:
      kind: githubApp
      capabilities:
        contents: read
        pullRequests: write
        issues: write
        checks: read
workingDirectory: /workspace/repo
tools:
  auto:
    kind: local
    implementation: auto
  github:
    kind: github
    tools:
      - pull_request_read
      - upsert_issue_comment
triggers:
  - name: pr-events
    events:
      - github.pull_request.opened
      - github.pull_request.reopened
      - github.pull_request.synchronize
    connection: github-acme
    where:
      $.github.repository.fullName: acme/widgets
    message: |
      Pull request #{{github.pullRequest.number}} has a review-triggering
      update (action: {{github.action}}; head {{github.pullRequest.headSha}}).
      Call checks.begin, then re-review the current head.
    checks:
      - name: pr-review
        displayName: Auto PR review
        description: Reviews this pull request and reports whether blocking issues were found.
        beginTimeout:
          seconds: 1200
          conclusion: failure
    routing:
      kind: bind
      target: github.pull_request
      onUnmatched: spawn
  - name: pr-conversation
    events:
      - github.issue_comment.created
      - github.pull_request_review.submitted
      - github.pull_request_review_comment.created
    connection: github-acme
    where:
      $.github.repository.fullName: acme/widgets
      $.github.auto.authored: false
      $.github.auto.externalBot: false
    message: |
      A PR conversation update arrived for PR #{{github.pullRequest.number}}.
      Read it and decide whether the review needs a refresh.
    routing:
      kind: bind
      target: github.pull_request
      onUnmatched: drop

triggers:
  - event: github.pull_request.closed
    connection: github-acme
    where:
      $.github.pullRequest.merged: true
    message: |
      PR #{{github.pullRequest.number}} merged
      ({{github.pullRequest.mergeCommitSha}}).
    routing:
      kind: bind
      target: github.pull_request
      onUnmatched: drop

​

Documentation Maintainer merge identity

1. Read fresh PR metadata with pull_request_read (get), the complete get_files inventory, and get_diff.
2. Corroborate the fresh metadata with list_commits or the mounted base-branch history to identify the commit that actually integrated the PR.
3. Use that resolved commit in <repo>#<pull-request-number>@<merge-commit-sha>. Search the existing documentation branch and open or closed PRs for the source marker before writing.

​

Pentester continuation after auto-authored updates

​

Repository Pentester review safeguards

• Review the exact window. Include all PRs, including auto-authored PRs, merged in [heartbeat.scheduledAt minus 24 hours, heartbeat.scheduledAt). A manual sweep records its supplied window end or current UTC time. Paginate search results and read complete get, get_files and get_diff evidence. Verify landed changes against historical PR metadata and a freshly fetched, verified main checkout; do not assume every merge has two parents. Assess interactions between changes and confirm that a candidate finding still exists on current main. Incomplete evidence is not a clean review.
• Carry unresolved work forward. Use auto.sessions.list with agent: pentester, includeArchived: true and limit: 50, then auto.sessions.conversation to read the previous daily run’s final Handoff notes. Unresolved items remain in scope beyond 24 hours. If that run failed or lacks a final message, also read the latest earlier usable handoff and record the gap. Missing history does not imply no pending work. The first daily run can use the previous per-PR final message as migration context. Continuity depends on explicit reads, not automatic predecessor-message injection.
• Open focused fixes, not verdicts. Confirmed Critical, High and materially exploitable Medium findings permit review-ready, non-draft remediation PRs on deterministic codex/security-<slug> branches. Search open and closed PRs first; reuse fixes and revalidate rejected approaches instead of reopening them automatically. Refresh main and recheck the flaw and patch before publication. Low-severity hardening alone does not warrant an automatic patch. Analysis and patch construction stay static: regression tests may be authored, but local execution is forbidden and ordinary PR CI supplies that validation. Disclose gaps or hand off an unsafe-to-fix finding rather than inventing a patch.
• Report once per window. Slack is required. Start one short #dev thread and finish with one result reply of at most five short bullets covering reviewed PRs, notable findings, patch links and blockers. Clean or no-merge windows need only a sentence, but still reconcile prior handoffs. Retries reuse the thread and existing finding PRs; urgent updates stay in the same thread. Record Slack failures in the final message rather than substituting GitHub comments or claiming delivery.
• Leave a usable handoff. End the final assistant message with window bounds, reviewed main SHA and PRs, coverage gaps, pending findings and next actions, remediation branch/PR state, resolved or withdrawn items, and Slack coordinates. Carry pending items until resolved and mark empty categories none. The ten-minute inactivity archive does not prevent later handoff reads. Do not create finding issues, external ledgers, dated reports or report-only PRs.

​

Canonical daily security sweep

• Verify the window and source. Review all PRs, including auto-authored PRs, merged in [heartbeat.scheduledAt minus 24 hours, heartbeat.scheduledAt). A manual sweep records its supplied window end or current UTC time. Paginate metadata and diffs, verify actual landed changes and current main, and require a reachable attacker path, impact and source evidence. An incomplete review is Evidence incomplete, not a clean result.
• Find the installed agent’s handoff. Call auto.session.get for the session and installed agent name, then auto.sessions.list with that name, includeArchived: true and limit: 50. Exclude the current session and read prior final Handoff notes through auto.sessions.conversation. This supports renamed installs instead of hard-coding pentester. Recover an earlier usable handoff when the last run was interrupted; report gaps and retain unresolved work beyond 24 hours. Continuity requires explicit reads, not scheduler-injected context.
• Patch only confirmed notable findings. Critical, High and materially exploitable Medium findings permit focused, non-draft remediation PRs on deterministic codex/security-<slug> branches. Search open and closed PRs, reuse fixes, revalidate rejected approaches and recheck current main before publication. Low-severity hardening alone does not authorize an automatic patch. Analysis and patch construction remain static: tests may be authored, but ordinary PR CI supplies execution. Never run repository code, dependency installs, hooks, exploits or live probes; access secrets; change provider security settings; edit other authors’ branches; merge; or enable auto-merge.
• Report and preserve continuity. Use one #dev thread per window and one result reply of at most five short bullets; a clean or no-merge result can be one sentence, but still reconcile prior handoffs. Retries reuse the thread and patch PRs. Record Slack failure in the final message rather than substituting GitHub comments. End with window bounds, reviewed SHA/PRs, coverage gaps, pending findings/actions, patch state, resolved or withdrawn findings and Slack coordinates, marking empty categories none. The 600-second inactivity archive does not prevent subsequent handoff reads.

​

github.pull_request.merge_conflict (synthetic)

triggers:
  - event: github.pull_request.merge_conflict
    connection: github-acme
    where:
      $.github.repository.fullName: acme/widgets
    message: |
      PR #{{github.pullRequest.number}} now conflicts with its base branch.
      Rebase onto {{github.pullRequest.baseRef}} and resolve the conflicts.
    routing:
      kind: bind
      target: github.pull_request
      onUnmatched: drop

​

Issues

​

github.issue.<action>

triggers:
  - event: github.issue.labeled
    connection: github-acme
    where:
      $.github.repository.fullName: acme/widgets
      $.github.label.name: agent-fix
    message: |
      Issue #{{github.issue.number}} was labeled for you:
      {{github.issue.title}}
      {{github.issue.htmlUrl}}

      Investigate and open a fix PR.
    routing:
      kind: spawn
      bind:
        target: github.issue

​

Comments

​

github.issue_comment.<action> — comments on pull requests

​

github.issue.comment.<action> — comments on plain issues

​

Reviews

​

github.pull_request_review.<action>

​

github.pull_request_review_comment.<action>

​

github.pull_request_review_thread.<action>

​

Checks and CI

​

github.check_run.completed

triggers:
  - event: github.check_run.completed
    connection: github-acme
    where:
      $.github.repository.fullName: acme/widgets
      $.github.checkRun.conclusion: failure
    message: |
      Check "{{github.checkRun.name}}" failed on PR
      #{{github.pullRequest.number}} (head {{github.checkRun.headSha}}).
      {{github.checkRun.htmlUrl}}

      Inspect the failure and push a fix.
    routing:
      kind: bind
      target: github.pull_request
      onUnmatched: drop

• Defers until idle. A delivered check completion never interrupts the session’s running turn; it waits for the session to go idle. A session mid-push is not derailed by the CI result of its previous head.
• Stale-head suppression. When the event routes through a github.pull_request bind, a check completion for a head auto has seen before that is no longer the PR’s current head is dropped — superseded runs never trigger redundant fix cycles. Completions for the current head, or for a head auto has never seen, always deliver.

​

Chief readiness-gate notifications

​

github.check_run.rerequested

​

github.check_run.requested_action.<identifier>

​

github.workflow_run.completed

triggers:
  - event: github.workflow_run.completed
    connection: github-acme
    where:
      $.github.repository.fullName: acme/widgets
      $.github.workflowRun.path: .github/workflows/deploy.yml
      $.github.workflowRun.headBranch: main
      $.github.workflowRun.conclusion: success
    message: |
      The deploy workflow passed on main.
      Run: {{github.workflowRun.htmlUrl}}
    routing:
      kind: deliver
      routeBy:
        kind: attributedSessions
      onUnmatched: drop

​

Pushes

​

github.push

​

Commit comments

​

github.commit_comment.created

triggers:
  - event: github.commit_comment.created
    connection: github-acme
    where:
      $.github.repository.fullName: acme/widgets
    message: |
      Deploy comment on {{github.comment.commitSha}}:
      {{github.comment.body}}
      {{github.comment.htmlUrl}}
    routing:
      kind: deliver
      routeBy:
        kind: attributedSessions
      onUnmatched: drop

​

Delivery behavior

• Echo suppression is yours to declare. The platform tags auto-authored content ($.github.auto.authored) and third-party bots ($.github.auto.externalBot) but does not filter them for you — add both filters to conversation triggers, as in the reviewer example.
• Closed-PR conversation is suppressed. Comment, review, review-comment, and review-thread events routed through a github.pull_request bind are dropped when the PR is already closed or merged. Archived work does not reopen sessions.
• Duplicate comment deliveries are deduplicated by body, so a redelivered webhook cannot make an agent process the same comment twice.
• auto’s own head pushes do route. A pull_request.synchronize caused by an auto session’s push is delivered like any other (with github.auto.authored: true); per-head-SHA dedup collapses redeliveries of the same commit to one routed event.
• Interrupt vs. defer. github.check_run.completed and github.workflow_run.completed defer until the session is idle; every other GitHub event interrupts the running turn immediately.

​

Quick reference