docs: document the GitHub integration for GA

[warp-agent-staging]

What and why

The native GitHub App integration (@oz-agent mentions on issues and pull requests) is going GA, but the docs had no page for it: the integrations hub, the Oz web app page, the triggers guides, and the CLI setup reference described only Slack, Linear, Jira, and GitHub Actions, and the Admin Panel docs described Enabled GitHub Orgs as an agent-API-key-only setting.

This adds a first-class GitHub integration page and corrects the surrounding pages so a reader can tell the three GitHub surfaces apart: the native GitHub App integration, GitHub Actions (oz-agent-action), and GitHub authorization for cloning and opening PRs.

Resolves REV-1872.

Changes

• New src/content/docs/platform/integrations/github.mdx — overview, how it works, supported triggers, follow-up behavior, requirements, four-step setup (App install → Enabled GitHub Orgs → run configuration → per-user GitHub connect), permissions and identity, limitations, troubleshooting, and removal, plus a sidebar entry in src/sidebar.ts.
• platform/integrations/index.mdx — GitHub listed as a first-class integration, with a callout separating it from GitHub Actions.
• platform/integrations/github-actions.mdx — callouts clarifying that Actions is workflow-defined, and how its @oz-agent mention example differs from the native integration.
• platform/triggers/index.mdx, guides/agent-workflows/how-to-run-unattended-agents.mdx — GitHub added as a trigger (table row, workflow pattern, next steps).
• platform/oz-web-app.mdx — Integrations page now documents the GitHub row and how it differs from the Slack/Linear guided flow.
• reference/cli/integration-setup.mdx — notes that the GitHub integration is not created with oz integration create.
• enterprise/team-management/admin-panel.mdx, platform/team-access-billing-and-identity.mdx — corrected: Enabled GitHub Orgs also determines which team owns GitHub-integration runs; documented GitHub identity mapping (connected GitHub account, not email) and what Warp receives from a mention.

Every claim was verified against the shipped implementation in warp-server — the @oz-agent handle default, the three supported webhook events (issue_comment created, pull_request_review_comment created, pull_request opened), the bot-sender exclusion, installation→team association, GitHub-user→Warp-user binding, the status-comment lifecycle, per-installation run configuration, and the automatic clone of the triggering repository. Behavior that is not on in production (for example the acknowledgement reaction, which is staging/local only) is deliberately not documented.

Scope note: no mention of Factories anywhere in the added content, per the request.

Verification

Documentation-only change, so it falls in the testing-exempt "pure data/copy" category — there is no behavior to cover with a regression test, and the repo has no test suite (AGENTS.md: "Run npm run build to validate all content compiles correctly"). The repo's documented checks were run instead:

• npm run build — passes; the new route /platform/integrations/github/ builds and the only warning is the pre-existing /404 route-conflict warning.
• python3 .agents/skills/check_for_broken_links/check_links.py --internal-only — 3248 internal links checked, 0 broken.
• python3 .agents/skills/style_lint/style_lint.py --changed — new page is clean apart from 4 known false positives (proper nouns: "GitHub App" in a heading, Oz by Warp, Enabled GitHub Orgs, Platform).
• Scope check: git diff origin/main contains no "Factory"/"Factories" in any added line.
• Rendered the page with npm run dev and verified in the browser: sidebar entry highlighted under Integrations, all headings present in the on-this-page TOC, both figures render, and the VARS expressions resolve to real text and oz.warp.dev links (no raw {VARS...} markup).

Computer-use screenshots

Originating thread: https://warpdev.slack.com/archives/C0BDQDW8V5E/p1785454926245089

Rework changes

Review cycle 1. Both findings were about the permission model and plan eligibility; the rest of the page is unchanged.

• Enterprise excluded by the eligibility wording (platform/integrations/github.mdx, Requirements) — implemented. The plan requirement now mirrors the access-and-billing page: "a Build, Max, or Business plan with at least 20 credits available, or an Enterprise plan with a team credit pool per your contract."
• Permission model was wrong: runs use the installation token, not the mentioner's OAuth token — implemented, after re-verifying against warp-server. UsesGitHubWebhookInstallationToken is true for every GitHubWebhookTaskSource, so GetGitHubTokenForTask always routes to getGitHubWebhookInstallationTokenForTask; the token is minted for the installation that delivered the event, and the repo list only selects and validates the installation ("they do not narrow the minted installation token's repository access"). Rewritten accordingly:
  • platform/integrations/github.mdx — "Permissions and identity" now separates access (the GitHub App installation token; cloning, branches, commits, PRs, and status comments are all the app's) from identity (the account binding sets run attribution, team ownership, and billing), and adds a caution that anyone who can comment in a covered repository can start a run with the installation's access. The Requirements and step 4 wording, the "opened no pull request" troubleshooting entry, and the limitations list were updated to match.
  • enterprise/team-management/admin-panel.mdx — the Enabled GitHub Orgs note no longer claims @oz-agent runs use the mentioning user's GitHub authorization.
  • platform/team-access-billing-and-identity.mdx — identity mapping, "Personal tokens vs. GitHub App tokens", and the GitHub data-and-permissions section now describe GitHub integration runs as installation-authenticated, alongside the existing agent-API-key flow.
• Also documented while verifying — every repository in a GitHub-triggered run (the triggering repo plus the environment's repos) must be covered by that same installation, and the environment must be a GitHub environment; otherwise the run fails to start (githubReposForInstallationToken, reposCoveredByInstallation).

Re-validated after the rework: npm run build passes, internal link check 0 broken of 3249, style lint unchanged on the new page (same 4 proper-noun false positives), and no "Factory"/"Factories" in any added line.

Cycle 2 (requester-authorized)

• Over-stated repository constraint (platform/integrations/github.mdx, limitations) — implemented. The reviewer was right that the run does not fail when an environment repository sits outside the installation: reposCoveredByInstallation skips uncovered repositories with a warning and only errors when none of the requested repositories are covered, and the server-populated trigger repo is always covered. The limitation is replaced with the two constraints the code does enforce: the configured environment must be a GitHub environment (githubReposForInstallationToken rejects another provider for webhook runs), and repositories the installation doesn't cover are simply unreachable for the run. The configuration-step note and the matching sentence on the access page were softened the same way.
• platform/oz-web-app.mdx quick reference row — implemented. The /integrations row now reads "Connect Slack, Linear, and GitHub to trigger agents from external tools", and the "Set up integrations" bullet in "When to use the web app" points at the GitHub page too, so the page no longer contradicts its own Integrations section.
• platform/team-access-billing-and-identity.mdx team access copy — implemented for both flagged spots. The individual-vs-team overview, the "What requires a team" list, and the "What teams enable" bullet now include Jira and the GitHub integration, and the team-level paragraph notes that GitHub is team-level in the same way once an admin enables the organization.

Re-validated after cycle 2: npm run build passes, internal link check 0 broken of 3253, style lint unchanged on the new page (same 4 proper-noun false positives), and no "Factory"/"Factories" in any added line.

Conversation: https://staging.warp.dev/conversation/24274946-3e5c-4441-84e2-d04818f10d0e
Run: https://oz.staging.warp.dev/runs/019fb573-e707-7450-8a07-037a3395e53e

This PR was generated with Oz.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Jul 31, 2026 4:15am

[warp-for-oss]

@warp-agent-staging[bot]

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-for-oss]

Overview

This PR adds a first-class GitHub integration page and updates related docs to distinguish the native GitHub App integration from GitHub Actions and GitHub authorization. The added coverage is broad, but a few plan/scope summaries still conflict with the new GitHub integration content and would leave readers with incorrect eligibility or availability guidance.

Concerns

• ⚠️ [IMPORTANT] src/content/docs/platform/oz-web-app.mdx still has an unchanged Quick reference row for /integrations that says the page lets users "Connect Slack and Linear to trigger agents from external tools." Since this PR updates the Integrations section to include GitHub, that top-level row should also include GitHub so the page does not contradict itself.
• ⚠️ [IMPORTANT] src/content/docs/platform/team-access-billing-and-identity.mdx still has unchanged Team access copy that lists integrations as Slack and Linear only, including the team capabilities and "What requires a team" sections. Update those summaries alongside the new identity/data handling copy so readers do not conclude GitHub integrations are excluded from team integrations.
• ⚠️ [IMPORTANT] The new GitHub integration requirements omit Enterprise from the supported integration plans; see the inline comment.

Verdict

Found: 0 critical, 3 important, 0 suggestions

Request changes

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[hongyi-chen]

nice ty!