> For the complete documentation index, see [llms.txt](/llms.txt).
> Markdown versions of each page are available by appending .md to any URL.

# Connect GitHub to your factory

Connect GitHub to your factory so issues, pull requests, reviews, and CI events start factory work and results post back 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** - 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 [Warp Factories web app](https://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.

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** (`github-factory-mention-assign`) - Start work when three filters are ANDed: the repository is one captured at create time, the issue or pull request has the `factory:<alias>` label, and **@warp-factory** is mentioned or assigned. See [Mention the factory](#mention-the-factory).
-   **Pull request closed or merged** (`github-pr-closed-or-merged`) - On pull requests with that same label, merging completes linked tracker items and the factory work item when Warp can resolve them. Closing without merging does nothing.

To confirm the connection works, add the factory’s label to a test issue, mention **@warp-factory**, and check that a work item starts in the factory’s [dashboard](/factories/factory-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](/factories/automations/#edit-filters-on-an-automation).

The CI failure triage automation in [`06-common-automations`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/06-common-automations) in the [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples) repository starts work when a workflow run fails on the default branch:

```
---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 findthe failing step. If the cause is small and clear, open a fix PR. Otherwiseopen an issue with the failing step, the error, and the commit range, andlink the run.
```

For a review automation that fires when pull requests open, see [`04-code-review-only`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/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, or a re-run of a Warp check |

Re-running a check starts work only for checks Warp itself created. GitHub doesn’t send re-run events for other providers’ checks, so those can’t trigger a factory.

For the exact `event` value each trigger uses in a definition file, see [triggers](/factories/factory-as-code/#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.

Use filters to route work precisely. For example, send failed runs of a specific workflow to a CI-repair automation.

## Mention the factory

Handing an issue or pull request to a factory takes two things:

1.  **Add the factory’s label.** Each factory has one, derived from its [alias](/factories/factory-as-code/#alias) (the **Foreman name** under **Settings** > **Identity** in the factory dashboard) as `factory:<alias>`. Warp normalizes the alias and shortens it if needed so the full name stays within GitHub’s label limit. For example, alias `payments` uses `factory:payments`, not the factory’s display name. Warp attempts, asynchronously and best-effort, to create the label in each configured GitHub user repository covered by an active GitHub App installation. If that attempt fails, the label can be missing from the list.
2.  Mention **@warp-factory** in the opening body or a new comment, or assign **@warp-factory** with GitHub’s assignee control.

**@warp-factory** is the shared GitHub account every factory listens through. The label decides which factory answers. Default automations already filter on that label, and agents add it to every issue or pull request they open or adopt.

If you mention **@warp-factory** without the label and no automation matches, Warp still tries to route the request when your GitHub account is linked to Warp:

-   **One accessible factory** is connected to the repository - Warp applies that factory’s label and starts work.
-   **More than one accessible factory** - Warp asks you to add the right `factory:<alias>` label and mention **@warp-factory** again.
-   **None** - Warp tells you to connect the repository or ask a factory admin for access.

Default automations fire on matching GitHub activity even if the author isn’t a Warp team member. Unlabeled fallback routing needs a linked Warp account.

Only new human-authored content counts: the body when you open an issue or pull request, a newly created conversation comment, a reply in an existing review thread, or a submitted review. Comment edits, bot content, and mentions inside markdown code do not trigger. A submitted review is one event that includes its summary and root inline comments; those inline comments do not start work on their own, and a mention in a review that is still pending does not start work.

The mentions automation starts with three ANDed filters: the repositories captured at create time, the `factory:<alias>` label, and **@warp-factory** as the mentioned user or assignee. Edit them to respond to a different handle, such as your own `@org/team` slug, or remove the label filter so any mention in the factory’s repositories starts work. Changing the alias or connected repositories later does not rewrite those filters, so edit the automation if they need to match the current setup.

## 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 the factory opens or adopts carry its `factory:<alias>` label. Warp attempts, asynchronously and best-effort, to remove the label from a configured GitHub user repository when you disconnect it or delete the factory, if an active GitHub App installation still covers that repository. If deletion fails, the label can be left behind. Renaming the alias does not rename existing labels, so an old label can remain. Delete leftovers like any other GitHub label.

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](/factories/automations/) 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](/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 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 passes with a summary of what the change does, or fails with the specific fields to fix. Require the check in branch protection to stop an invalid definition 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 mention doesn’t start work

Confirm the mention is in new human-authored content, not an edit, a bot comment, or markdown code. The handle is **@warp-factory**, not **@warp-agent**. Then check that the issue or pull request has the factory’s `factory:<alias>` label.

If the label is missing, Warp routes an unlabeled mention only when your GitHub account is linked to Warp and you can access exactly one factory connected to the repository. If more than one accessible factory is connected to the repo, add the right label and mention **@warp-factory** again.

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](/factories/factory-as-code/) in a GitHub repository. Confirm the pull request targets the branch the factory runs from, that it changes files in the factory’s definition directory, and that the GitHub App covers the repository.