Connect a factory to GitHub

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 - Install the app and grant it access to at least one repository the factory uses. Follow the GitHub integration setup if you haven’t already. If your team already installed the app for the platform GitHub integration, the same installation covers factories.
• A factory with GitHub repositories - The factory must include at least one repository granted to the Warp GitHub App installation.

Connect GitHub to a factory

1. Open the Warp Factories web app, click New factory to open the factory setup flow, and 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. After setup completes, the factory opens in its control room. Click Automations.
4. Create an automation or edit a default one, choose the receiving agent, and add any Additional instructions.
5. Under Triggers, click Add trigger.
6. Choose GitHub, then choose an event.
7. Select a repository, then use More filters to narrow which activity matches.
8. 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 editable default automations: one for agent mentions and assignments (see Mention the factory), and one for pull requests that close or merge. When Linear or Jira is connected, the pull request automation can also complete the linked ticket after a merge.

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 posted by bots are all 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 reacts to the activity it handles and 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 the existing work item, with its earlier context and history, rather than starting a new one.

Issues and pull requests created by the factory carry a factory:<alias> label. Warp attempts to create the label in each connected repository and attempts to remove it when you remove the repository or delete the factory. You don’t create it manually, though stale labels may require manual cleanup if GitHub removal fails.

Factory-created branches and pull requests follow the repository’s normal rules: branch protection, required reviews, and merge requirements all 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. A run can read and write whatever your team granted the Warp GitHub App at install time — those repositories, with those permissions, and nothing else. Selecting repositories for a factory or tightening automation filters changes when work starts, not what a running agent can access; 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 — its configuration lives as files like factory.yaml in a registered directory — Warp reviews configuration changes the way CI reviews code. When a pull request targeting the production branch changes files under that directory, a warp/factory-config check runs on the pull request: it passes with a summary of what would change, or fails with diagnostics on the files that need fixing. Require the check in branch protection to keep 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.