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, 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.

That’s all the setup GitHub needs. A new factory arrives with two automations already switched on, so it responds to GitHub activity right away:

• Mentions and assignments - Start work by mentioning @warp-factory. See Mention the factory below.
• Pull request merges - Close out work by merging a pull request with your factory’s label. Any work items linked to the pull request move to their tracker’s completed state. Closing without merging does nothing.

To confirm the connection works, mention @warp-factory on a test issue and check that a work item starts in the factory’s dashboard.

Add a custom automation

The defaults cover mentions, assignments, and pull request completion. To start work from any other GitHub activity, such as a failed CI run or a review request, add an automation with a GitHub trigger for that event, then narrow it with the filters below. To learn how to edit those filters, see Automations.

The CI failure triage automation in 06-common-automations in the warp-factory-examples repository starts work when a workflow run fails on the default branch:

automations/ci-failure-triage/automation.md

---
triggers:
  - provider: github
    event: workflow_run_completed
    filter:
      repos: [acme/api-service]
      branches: [main]
      conclusions: [failure]
---
A workflow run failed on the default branch. Read the run's logs and find
the failing step. If the cause is small and clear, open a fix PR. Otherwise
open an issue with the failing step, the error, and the commit range, and
link the run.

For a review automation that fires when pull requests open, see 04-code-review-only.

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, a completed check suite or workflow run

For the exact event value each trigger uses in a definition file, see triggers.

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

On check suite and workflow run triggers, Labels and Authors match the pull request linked to the run rather than the run itself.

Mention the factory

Add the factory’s factory:<alias> label to the issue or pull request, then mention @warp-factory in the opening body or a new comment. The alias is the Foreman name in the factory dashboard’s Identity settings. Warp creates the label with the factory, and the factory replies in the same thread.

Without the label, a linked Warp account can still route the mention:

• One accessible factory - Warp adds its label and starts work.
• Multiple accessible factories - Warp asks you to add the right label and mention @warp-factory again.
• No accessible factory - Warp asks you to connect the repository or request access.

Default automations can respond to authors whose GitHub accounts aren’t linked to Warp.

Only new content counts as a mention. Edits to existing comments, mentions inside code blocks, and mentions from bots are ignored.

You can change what the factory answers to. The handle and the label are the starting filters on its mentions automation: edit them to respond to a different handle, such as your own @org/team slug, or remove the label filter so that any mention in the factory’s repositories starts work.

How the factory responds on GitHub

The factory posts progress and links in the originating issue, pull request, or review thread. Pushes and workflow runs report on the work item instead. New activity on an existing thread continues the same work item.

Issues and pull requests the factory opens or adopts carry its factory:<alias> label. Warp removes it when you disconnect the repository or delete the factory. Delete old labels after renaming the alias.

Branches and pull requests the factory creates 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. Agents get exactly the repositories and permissions the installation grants, so change the installation to change access. Automation filters only change when work starts.
• 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 changes to it the way CI reviews code. Open a pull request that touches the definition files and a warp/factory-config check runs: it validates the head commit and dry-runs the change against your team, so it also catches a secret, runner, MCP server, or model that doesn’t exist. It passes with a summary of what merging would create, update, and delete, or fails with the specific fields to fix. If the definition lives in a subdirectory of the repository, the directory is appended to the check name, as in warp/factory-config (factory). Require the check in branch protection to stop an invalid definition from merging.

These checks validate configuration files only and don’t create work items. Unchanged definitions pass immediately, so requiring the check doesn’t block unrelated work. To check a definition before opening a pull request, see Validate a definition.

Troubleshooting

A mention doesn’t start work

Confirm the mention is new human-authored content, not an edit, bot comment, or markdown code. Use @warp-factory, and add the factory’s factory:<alias> label. Without a label, routing works only when your linked Warp account can access exactly one factory connected to the repository.

If you renamed the alias or changed repositories after creating the factory, the default automation’s filters still use the original snapshot. Edit that automation so the label and repository filters match.

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 branch the factory runs from and that the GitHub App covers the repository.