Connect GitHub to your factory

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 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 Warp Factories web app at platform.warp.dev, 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, 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). 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

Trigger	Supported activity
Issues	Created, labeled, assigned, or agent mentioned
Pull requests	Opened, marked ready, reopened, updated with commits, assigned, labeled, mentioned, closed, or merged
Reviews	Review requested or review submitted
Code and CI	Push, completed check suite or workflow run, or a re-requested Warp-owned check

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 on the GitHub integration page.

Factory-definition pull request checks

If the factory’s definition is managed 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 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.