docs(factories): document GitHub integration

src/content/docs/factories/integrations/github.mdx

@@ -1,9 +1,127 @@
 ---
 title: Connect GitHub to your factory
 description: >-
-  GitHub integration documentation for Warp Factories will be added in a follow-up PR.
+  Connect a factory to GitHub so issues, pull requests, reviews, and CI events
+  start factory work and results post back to GitHub.
 sidebar:
   label: "GitHub"
+topic: factories
 ---
+import { VARS } from '@data/vars';
 
-GitHub integration documentation for Warp Factories will land in a follow-up PR.
+When you connect a factory to GitHub, repository activity starts work in your factory. Issues, pull requests, reviews, and CI events can all trigger automations, and the factory posts results back to GitHub as comments, branches, and pull requests.
+
+## Prerequisites
+
+* **The Warp GitHub App** - Follow the [GitHub integration setup](/platform/integrations/github/) if you haven't already. One installation serves both the platform integration and factories.
+* **A factory with GitHub repositories** - The app must have access to at least one of the factory's repositories.
+
+## Connect GitHub to a factory
+
+1. In the {VARS.FACTORY_WEB_APP} at <a href={VARS.FACTORY_WEB_APP_URL}>platform.warp.dev</a>, click **+** next to **Factories** to open the setup wizard, then choose **I want to use repos from GitHub** under **Connect your code host**.
+2. Under **Select your repos**, choose the repositories to provide code and context for the factory.
+3. In the factory's [control room](/factories/control-room/), click **Automations**. Create an automation or edit a default one, choose the receiving agent, and add any **Additional instructions**.
+4. Under **Triggers**, click **Add trigger**.
+5. Choose **GitHub**, then choose an event.
+6. Select a repository, then use **More filters** to narrow which activity matches.
+7. Click **Save**. To confirm the automation works, trigger a matching event in GitHub, such as opening a test issue, and check that a work item starts in the control room.
+
+Managed GitHub factories start with two editable default automations. The first handles agent mentions and assignments (see [Mention the factory](#mention-the-factory)). The second runs when a pull request closes or merges: on a merge it finds the work items linked from the pull request and moves each one to its tracker's completed state, and on a close without a merge it does nothing.
+
+## Supported triggers
+
+<table>
+<colgroup>
+<col style="width: 22%" />
+<col />
+</colgroup>
+<thead>
+<tr><th>Trigger</th><th>Supported activity</th></tr>
+</thead>
+<tbody>
+<tr><td>Issues</td><td>Created, labeled, assigned, or agent mentioned</td></tr>
+<tr><td>Pull requests</td><td>Opened, marked ready, reopened, updated with commits, assigned, labeled, mentioned, closed, or merged</td></tr>
+<tr><td>Reviews</td><td>Review requested or review submitted</td></tr>
+<tr><td>Code and CI</td><td>Push, completed check suite or workflow run, or a re-requested Warp-owned check</td></tr>
+</tbody>
+</table>
+
+Re-requesting a check triggers the factory only when the Warp GitHub App created that check. GitHub doesn't deliver re-request events for third-party CI checks.
+
+### Automation filters
+
+Every trigger names the repository it watches. The remaining filters appear only on the event types they apply to:
+
+| Filter | Matches | Appears on |
+| --- | --- | --- |
+| **Branches** | The pushed branch, or a CI run's head branch | Push and CI triggers |
+| **Base branches** | The branch the pull request targets | Pull request triggers |
+| **Paths** | The files the change touches | Push and pull request triggers |
+| **Labels** | Labels on the issue or pull request | Issue, pull request, review submitted, and CI triggers |
+| **Authors** | Who opened the issue or pull request | Issue, pull request, and CI triggers |
+| **Assignees** | Who the issue or pull request is assigned to | Issue and pull request triggers |
+| **Mentioned users or teams** | Which user or team is @mentioned | Mention and review submitted triggers |
+| **Reviewers** and **Reviewer teams** | Who review was requested from | Review requested triggers |
+| **Review states** | Whether the review approved, requested changes, or commented | Review submitted triggers |
+| **Workflows** | The GitHub Actions workflow, by name | Workflow run triggers |
+| **Conclusions** | The run's result: success, failure, cancelled, and so on | Check suite and workflow run triggers |
+
+CI payloads don't carry issue or label data, so on check suite and workflow run triggers, **Labels** and **Authors** match against the pull request linked to the run.
+
+Use filters to route work precisely. For example, send failed runs of a specific workflow to a CI-repair automation.
+
+## Mention the factory
+
+A factory doesn't get its own GitHub handle. Every factory listens through the same Warp agent account, **@oz-agent**, and the factory's `factory:<alias>` label decides which factory a mention reaches:
+
+1. Apply the factory's `factory:<alias>` label to the issue or pull request. Warp creates the label in each connected repository.
+2. Assign **@oz-agent** to the issue or pull request, or mention **@oz-agent** in the body or in any new comment.
+
+The default mentions-and-assignments automation starts a work item in the matching factory, and the factory replies in the same thread. The label is what routes the request. A mention without the factory's label doesn't match the default automation.
+
+Mentions count only in new content; edits to existing comments, mentions inside code blocks, and mentions from bots are ignored.
+
+The handle and label are default filter values, not fixed rules. Edit the automation's **Mentioned users or teams** filter to respond to other handles, such as your own `@org/team` slug, or remove the label filter to catch every mention in the factory's repositories.
+
+## How the factory responds on GitHub
+
+The factory posts progress comments in the originating issue, pull request, or review thread, with links to the run and to any branches or pull requests it creates. Events without a comment surface, such as a push or a workflow run, report their results on the work item instead.
+
+New activity on an issue, pull request, or review thread the factory is already working on continues that work item instead of starting a new one.
+
+Issues and pull requests created by the factory carry a `factory:<alias>` label. Warp adds that label to every connected repository and removes it when you disconnect a repository or delete the factory, so you never create it by hand. Both passes are best-effort: if GitHub rejects one, a stale label can linger and needs deleting manually.
+
+Factory-created branches and pull requests follow the repository's normal rules: branch protection, required reviews, and merge requirements still apply.
+
+## Permissions
+
+Runs authenticate with the GitHub App installation, not with the account of the person whose activity triggered them:
+
+* **The app installation decides what agents can reach.** Agents get exactly the repositories and permissions the installation grants. Factory repositories and automation filters control when work starts, not what a running agent can reach. To change access, change the installation.
+* **Anyone who can create matching activity can start work.** The event author doesn't need to be a Warp team member. Use author, label, and branch filters to control what starts runs.
+
+For the full credential model, see [Permissions and identity](/platform/integrations/github/#permissions-and-identity) on the GitHub integration page.
+
+## Factory-definition pull request checks
+
+If the factory's [definition is managed as code](/factories/factory-as-code/) in a GitHub repository, Warp reviews configuration changes like CI reviews code. When a pull request targets the production branch and changes files in the registered factory directory, a **warp/factory-config** check runs: it passes with a summary of the change, or fails with diagnostics on what to fix. Require the check in branch protection to block invalid definitions from merging.
+
+These checks validate the factory's configuration files only. They don't create work items, and pull requests that don't touch the factory directory don't get the check.
+
+## Troubleshooting
+
+### A GitHub event doesn't start work
+
+Confirm the app installation covers the event's repository, the repository belongs to the factory, and the automation includes that event. Then check each filter; a label, author, branch, workflow, conclusion, or state mismatch prevents routing.
+
+### Filter options don't load
+
+Select a repository first. If the automation editor shows **Connect GitHub**, complete the account connection and retry. You can enter a value manually when suggestions are unavailable.
+
+### An agent can't push a branch or open a pull request
+
+Check that the installation still covers the target repository and grants the required write permissions. Automation filters don't affect GitHub authorization.
+
+### A factory-definition check doesn't appear
+
+The check runs only for factories whose [definition is managed as code](/factories/factory-as-code/) in a GitHub repository. Confirm the pull request targets the definition's production branch, changes files under the registered factory directory, and that the GitHub App covers the repository.