Open-Inspect's GitHub integration lets your team start agent work from pull requests. The GitHub Bot can automatically review new PRs and respond when you mention it in PR comments or inline review threads.
This guide is for people using the GitHub integration day to day. If you are installing the GitHub App or deploying the bot worker, start with Create GitHub App and Complete GitHub Bot Setup.
- Make sure the GitHub App is installed on the repository.
- To get an automatic review, open a non-draft PR in a repository where auto-review is enabled.
- To ask for analysis or a reply, mention the bot in a PR comment:
@my-app[bot] can you explain why the checkout test is failing? - For line-specific discussion, mention the bot in an inline PR review comment.
- Watch for the eyes reaction, which means the bot accepted the request.
- Open the Open-Inspect web app to watch the full session.
| Workflow | How it works |
|---|---|
| Auto-review new PRs | Review non-draft PRs when they are opened, if auto-review is enabled |
| Respond to PR comments | Mention the bot in a PR conversation comment |
| Respond to review threads | Mention the bot in an inline review comment |
| Post back to GitHub | Submit a PR review, reply to a review thread, or post a PR summary comment |
| Customize behavior | Set repository scope, trigger users, models, and custom instructions |
Open-Inspect does not use GitHub slash commands today, and it does not support requesting the GitHub
App bot through the PR reviewer picker. Use auto-review or @mention comments instead.
Auto-review new PRs is the deprecated, workspace-owned review-on-open path. It still works and does not use mention team routing. For team-owned event-driven reviews, use a GitHub Event automation owned by the intended team instead. Deprecation does not disable the existing setting.
When Auto-review new PRs is enabled, Open-Inspect starts a review session for newly opened, non-draft PRs in enabled repositories. The agent inspects the PR diff and posts a GitHub review.
Auto-review is skipped when:
- The PR is a draft
- The PR was opened by the GitHub App bot itself without its login explicitly allowed as a trigger
- The repository is outside the configured GitHub Bot scope
- The PR opener is not allowed to trigger the bot
- Auto-review is disabled globally or for that repository
Converting a draft PR to ready for review does not start the same auto-review path. If you need a follow-up after a draft becomes ready, mention the bot in a PR comment.
The agent can submit a general review comment, approve the PR, request changes, or add inline review comments when useful.
An explicitly allowed App bot can trigger review of its own PR, but that self-review can only comment, not approve or request changes.
Mention the GitHub App bot in a PR conversation comment to ask for analysis, a follow-up answer, or a GitHub reply:
@my-app[bot] can you explain why this retry path is failing?
Open-Inspect strips the bot mention before sending the request to the agent. The rest of the comment becomes the prompt.
Start the request with !model or !reasoning to override the configured model or reasoning effort
for the session that comment starts:
@my-app[bot] !model openai/gpt-5.6-sol !reasoning high investigate the flaky test
The flags use the same syntax as Slack: each accepts a space or colon before its value (such as
!model:anthropic/claude-sonnet-4-6 or !reasoning:max), and any flags must appear together at the
start of the request, right after the bot mention. Flags later in the comment are treated as part of
the request. Models must be enabled under Settings > Models, and the reasoning value must be
supported by the selected model. A model flag without !reasoning keeps the configured reasoning
effort when the new model supports it, and otherwise uses the model's default.
If a flag is invalid, the bot replies with a PR comment explaining why and does not start a session. Flags work in PR conversation comments and inline review threads. Auto-reviews and review requests always use the configured model.
If the configured Agent harness cannot run the resolved model, the bot replies on the PR and
creates no session; it does not switch to OpenCode. Retry a mention with a compatible !model,
update the default model, or change the GitHub integration harness.
When you mention the bot in a PR review thread, Open-Inspect includes the file path and diff context from that thread. The agent can reply directly to the review thread and can also post a summary comment on the PR.
Comment-triggered sessions currently start from the repository default branch, not the PR head branch. Use them for responses and review-thread discussion rather than asking the agent to push commits to the existing PR branch.
Each accepted GitHub webhook starts a new Open-Inspect session. GitHub comments do not continue an existing session the way Slack thread replies do. The agent still reads the current PR conversation when it needs context.
Comment-triggered actions only run on pull requests. Mentions on ordinary GitHub issues are ignored. Comments from the bot itself are also ignored so the bot does not respond to its own output.
Before creating a mention session, the bot asks the control plane for ownership using the numeric GitHub repository ID and PR number. Routing follows this order:
- If the PR is linked to an existing Open-Inspect session, use that session's owning team (or workspace ownership). This is only a routing hint: it neither resumes nor grants access to that session, including a private one.
- Otherwise, resolve the sender's linked GitHub identity and current teams with a repository or installation grant covering the triggering repository. Exactly one eligible team wins.
- If multiple teams qualify, use the sender's most recent session on that repository in a still eligible team. If none resolves the ambiguity, use workspace ownership. Missing identity or no eligible team also falls back to workspace ownership.
A route lookup failure stops the request rather than guessing workspace ownership. GitHub trigger gates still run, and session creation separately checks membership, team state, and repository grants. A configured default environment is used only when ownership is compatible, it includes the trigger repository, and the sender passes its repository checks; otherwise the target falls back to the triggering repository. Workspace fallback can still be refused if the workspace requires team ownership for new sessions.
The runtime default for TEAMS_ENFORCEMENT remains shadow, not on; routing a session to a team
does not imply full team-read isolation in that mode.
When a GitHub request is accepted, the bot adds an eyes reaction. That reaction is best-effort; if GitHub rejects the reaction, the session can still start.
For auto-review workflows, the agent posts the review result back to the PR. Depending on what it finds, that may be a general review comment, an approval, a request for changes, or inline review comments.
For @mention workflows, the agent posts a PR comment summarizing its response or answering the
question. If the request came from an inline review thread, the agent may also reply in that thread.
GitHub does not receive the same managed completion message that Slack receives. After the initial eyes reaction, GitHub-facing output is written by the agent from inside the session. Use the Open-Inspect web app to watch live progress, inspect logs, or see artifacts.
Open the web app and go to Settings > Integrations > GitHub to configure the GitHub Bot.
| Setting | What it controls |
|---|---|
| Default model | Model used for GitHub-started sessions when a repository does not override it |
| Default reasoning effort | Reasoning depth used with the selected default model |
| Agent harness | Harness that runs GitHub-started sessions (OpenCode default, or Claude Agent) |
| Auto-review new PRs | Whether new non-draft PRs should be reviewed automatically |
| Repository Scope | Whether the bot responds in all accessible repositories or only selected repositories |
| Allowed Trigger Users | Who can trigger the bot from GitHub |
If no GitHub Bot settings are configured, Open-Inspect uses permissive defaults: all repositories available to the GitHub App are in scope, auto-review is enabled, and users with write, maintain, or admin access to the repository can trigger the bot.
If repository scope is set to Selected repositories and no repositories are selected, direct GitHub Bot workflows are disabled. If Only specific users is selected and the user list is empty, no one can trigger direct bot workflows for that scope.
These settings do not gate GitHub event automations. Automations are matched separately by their repository, event type, enabled state, and trigger conditions.
Event automations match the numeric GitHub repository ID, not just owner/name, and retain the
automation's saved owning team rather than using the mention sender's team. A team-owned automation
needs a current grant covering that repository at admission and launch. Losing the grant prevents a
run; restoring it allows a later event to run, not a replay of previously skipped events. Repository
renames retain identity through the numeric ID, while run targets use the event's current owner and
name. These checks are independent of the deprecated workspace auto-review setting.
Upgrade the GitHub bot and control plane together. The control plane rejects event envelopes without a numeric repository ID, so an older bot's events are not routed. Automations saved before repository IDs were recorded no longer match events by name; open each one, reselect its repositories, and save to resolve their IDs.
| Setting | What it controls |
|---|---|
| Model and reasoning effort | Model and reasoning depth for GitHub-started sessions, when configured |
| Agent harness | Harness for GitHub-started sessions; incompatible models are refused |
| Code Review Instructions | Extra guidance appended to PR review prompts |
| Comment Action Instructions | Extra guidance appended to @mention action prompts |
| Repository Overrides | Per-repository overrides for model, harness, reasoning, instructions, and behavior |
Repository overrides take priority over global defaults for the repository they apply to. Omitted
harness and model fields inherit individually from the global settings. If neither level sets a
harness, it is OpenCode; if neither sets a model, sessions use the deployment default model. A
!model or !reasoning flag at the start of a mention overrides
the corresponding model or effort setting for that one session, not the harness.
Explicitly choosing a restricted harness such as Claude Agent requires a compatible default model at the same settings level (global or repository), not an inherited model. The settings form and control plane reject a missing model or an incompatible pair at that level. Use system default is not offered when explicitly choosing Claude Agent. Save validation does not check the merged global/repository pair: a model-only repository override can inherit an incompatible global harness, in which case the bot refuses the launch.
Open-Inspect can sign normal agent-created commits with one deployment-wide OpenSSH Ed25519 key. The identities remain deliberately separate:
| Git/GitHub role | Identity |
|---|---|
| Commit author | The trusted prompting GitHub user, when available; otherwise Open-Inspect |
| Committer and signer | The dedicated Open-Inspect signing account |
| Branch pusher | The existing GitHub App |
| Pull request author | The prompting user's OAuth identity when available; otherwise the existing App fallback |
This makes the signature an attestation by the Open-Inspect deployment, not a cryptographic claim that the attributed user personally signed the commit. GitHub repository rules remain the server-side enforcement boundary for rejecting unsigned commits.
To configure signing, open Settings > Integrations > GitHub > Commit signing:
- Create or recover a dedicated GitHub account for the signing identity. It does not need repository access because the GitHub App continues to push branches.
- Generate an unencrypted OpenSSH Ed25519 key and add its public key to that account as a signing key.
- Enter the fixed committer name/email and private key in the write-only form. The committer email must belong to the dedicated account.
- Save, then exercise a normal commit and a history rewrite in a non-critical repository before requiring signed commits.
The private key is encrypted in the control-plane database. The settings page reads back only the
derived public key, fingerprint, fixed identity, and last update time; it never repopulates the
private-key field. Sandboxes receive only the public key. For each commit, a stateless Git signer
derives its fingerprint from that public key and sends the bounded unsigned commit buffer to the
authenticated control-plane signing endpoint. The control plane decrypts the active key in
request-local memory and returns a complete git-namespace SSH signature. The private key is never
delivered to a sandbox file, environment, process, or provider snapshot.
The unsigned commit buffer contains Git headers, author/committer identities, and the commit message. It does not contain file contents or diffs. Open-Inspect does not interpret, retain, or log the buffer and does not maintain a signature ledger.
For rotation, register the replacement public key on GitHub before replacing the private key in Open-Inspect, then remove the old public key after existing signing requests drain. A request that already resolved the old key may complete; later requests for that fingerprint fail and retry after the next prompt refresh with the new public key. Disabling deletes the active database ciphertext. Requests that resolve configuration afterward fail closed, and running sandboxes remove Git signing configuration on their next prompt refresh.
Important limitations:
- GitHub vigilant mode shows attributed commits as Partially verified because the author and committer are intentionally different.
- GitHub-created merge or squash commits follow the repository's merge-signing behavior; the signature on the branch commit does not automatically carry onto a newly created merge commit.
- Commit creation and history rewrites require the control plane to be available. Rewriting multiple commits performs one signing round trip per recreated commit, with no unsigned fallback.
- Any process in a live sandbox that can use its session token can ask the control plane to sign an arbitrary bounded commit buffer. Remote signing prevents reusable-key extraction; it does not make the sandbox trustworthy or add commit-policy enforcement.
- Sessions already running when signing support is deployed must be recreated so they start the updated shared runtime. Provider images and snapshots do not need a preinstalled signer wrapper; the checked-in launcher is installed with the runtime's other standalone commands during startup.
- Repository access is deployment-scoped through the configured GitHub App installation. To restrict what Open-Inspect can access, install the GitHub App only on intended repositories and use Repository Scope for an additional bot-level filter.
- The same GitHub App is used for OAuth and repository access. GitHub App credentials and webhook secrets stay server-side.
- By default, trigger access is checked against GitHub repository permission and requires write, maintain, or admin access. If you configure Only specific users, that list becomes the trigger gate for the configured scope.
- Auto-review skips draft PRs. An explicitly allowed App bot can trigger a comment-only self-review.
Manual
@mentiontriggers still pass the repository and user gates, then team routing and creation checks. - The bot ignores bot-authored comments, ordinary issue comments, and comments that do not mention the bot.
- If the bot cannot load its GitHub integration settings, it fails closed and does not start direct bot sessions.
- Initial prompts mark selected GitHub fields as untrusted. Code-review prompts wrap PR title, author, branches, and description; comment-triggered prompts wrap the triggering comment.
- Review-thread file and diff context, plus GitHub context later read by the agent, are not separately transformed by the bot.
- Webhooks are verified before Open-Inspect acts on them. Duplicate webhook deliveries are deduplicated so GitHub retries do not normally create duplicate direct bot sessions.
Check that the GitHub App is installed on the repository and that the GitHub Bot worker is enabled.
Then confirm the webhook URL, webhook secret, subscribed events, and github_bot_username in
Complete GitHub Bot Setup.
Also check Settings > Integrations > GitHub. For direct GitHub Bot workflows, the repository may be outside the selected repository scope, or the triggering user may be outside the allowed user list.
The deprecated workspace auto-review only runs for newly opened, non-draft PRs. It is skipped for draft PRs, disabled repositories, and users who are not allowed to trigger the bot. An App-authored PR needs the App bot login explicitly allowed; its self-review can only comment.
If a PR was converted from draft to ready for review, mention the bot in a PR comment instead.
Mentions must be in a pull request conversation comment or PR review thread. Mentions on ordinary
GitHub issues are ignored. Use the bot's full GitHub username, including [bot], such as
@my-app[bot].
The eyes reaction means the bot accepted the request. GitHub completion output is posted by the agent, not by a managed bot callback. The session may still be running, or the agent may have failed after the request was accepted. Open the Open-Inspect web app to inspect the session.
Check Settings > Integrations > GitHub. Repository overrides take priority over global defaults.
Changes apply to new GitHub-triggered sessions. A !model or !reasoning flag at the start of the
mention overrides both for that session.
Limit the GitHub App installation to the repositories Open-Inspect should access. You can also set Repository Scope to Selected repositories in the GitHub integration settings.