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

# Connect GitLab to your factory

Connect GitLab to your factory so merge request events and bot mentions start factory work and results post back as comments and merge requests.

When you connect a factory to GitLab, project activity starts work in your factory. Merge request events and bot mentions trigger automations, and the factory posts results back to GitLab as comments, branches, and merge requests.

## Prerequisites

-   **GitLab.com** - The integration supports GitLab.com only, not self-managed GitLab instances. To use a self-managed instance with standalone cloud agents instead, see the [GitLab access token setup](/platform/integrations/gitlab/).
-   **A top-level GitLab group you own** - Connecting GitLab links one top-level group to your Warp workspace, one-to-one. Creating the link requires the Owner role on the group and workspace admin permissions in Warp.
-   **A GitLab plan with service accounts and group webhooks** - Warp provisions service accounts in your group and installs a group webhook. Both are GitLab Premium and Ultimate features. On a plan without group webhooks, factory credentials still work, but GitLab cannot trigger runs.

## Your factory’s GitLab identity

Each factory gets its own GitLab service account — its bot. The bot is the factory’s identity on GitLab: its username is the handle you mention, runs act as it, and the projects it belongs to are exactly the ones you select for the factory. Warp creates and retires these accounts for you.

## Connect GitLab to a factory

When you create a factory, choose **I want to use repos from GitLab** as the code host, then:

1.  **Connect a top-level group.** Warp links it to your Warp workspace and sets up event delivery from it. A group already connected to your workspace is selected for you.
2.  **Select the projects the factory works in.** Anything under the connected group is available, including projects in subgroups.

That’s the setup. A GitLab factory starts with one default automation, **gitlab-bot-mentions**, so mentioning the bot in a merge request comment starts work right away. To confirm it, do exactly that: comment on a merge request in one of the selected projects, mention the bot, and watch for a work item in the factory’s [dashboard](/factories/factory-dashboard/).

To start work from merge request events as well, add a **Merge request** trigger to an automation — see [automation filters](/factories/automation-filters/#edit-filters-on-an-automation).

## Supported triggers

| Trigger | Fires when |
| --- | --- |
| Merge request | A merge request is opened, updated, closed, reopened, merged, or approved |
| Bot mentioned | A new comment mentions the factory’s bot username |

### Automation filters

| Filter | Matches | Appears on |
| --- | --- | --- |
| **Project** | The GitLab project the event came from | Both triggers |
| **Actions** | What happened to the merge request, such as opened, updated, or merged | Merge request |
| **Base branch** | The branch the merge request targets | Merge request |

The **Bot mentioned** trigger always listens for the factory’s own bot. You can’t point it at a different username.

## Mention the factory

Each GitLab factory has its own bot account, so the mention itself routes the request. There is no shared handle or routing label to apply. To mention the factory:

1.  Open a merge request in one of the factory’s projects.
2.  Post a comment that mentions the factory’s bot username and includes an instruction.

The **gitlab-bot-mentions** automation starts a work item, and the factory replies in the same thread. To find the bot’s username, check that automation’s trigger in the [factory dashboard](/factories/factory-dashboard/).

Mentions count only in new comments. Edits and activity from Warp’s own service accounts never trigger work, so a factory can’t re-trigger itself or a sibling factory.

## How the factory responds on GitLab

The factory acts on GitLab as its bot account:

-   **Replies in the thread it was mentioned in** - Its comments link back to the run session and the factory work item. New comments on the same merge request continue that work item instead of starting a new one.
-   **Pushes branches and opens draft merge requests** - Branches are named `factory/<slug>`, and merge requests open as drafts that the factory marks ready when the work is done. Commits and comments attribute to the bot’s GitLab profile.
-   **Labels what it touches** - Merge requests and issues the factory opens or adopts carry its own label, named `factory:` followed by the factory’s Foreman name.
-   **Posts review feedback as comments** - A review lands as a summary note plus inline discussions on the diff. When a later revision addresses a finding, the factory replies in that discussion and resolves it.

The factory never merges or approves a merge request, and your project’s protection and approval rules apply to everything the bot does.

## Permissions

Runs authenticate as the factory’s bot account, not as the person whose activity triggered them:

-   **The bot’s project membership decides what runs can reach.** A run can reach the projects the factory selected, with the bot’s Developer role, and nothing else. To change what it can reach, change the factory’s projects — [automation filters](/factories/automation-filters/) only change when work starts.
-   **Anyone who can create matching activity can start work.** The commenter doesn’t need to be a Warp team member. Use project, action, and base-branch filters to control what starts runs.

Disconnecting GitLab from your workspace retires every factory bot along with it.

## Definitions as code

If the factory’s [definition is managed as code](/factories/factory-as-code/), declare GitLab triggers in an automation file:

```
---enabled: trueagent: foremantriggers:  - provider: gitlab    event: merge_request    filter:      repos: [my-group/my-app]      actions: [open]---
Triage newly opened merge requests and post an initial review.
```

A `bot_mentioned` trigger takes only a `repos` filter — leave `mentioned` out, since the bot username isn’t yours to set.

A GitLab-backed factory can still be managed as code, but the definition itself lives either in Warp or in a GitHub repository — GitLab is not yet available as a definition host. See [where the definition lives](/factories/factory-as-code/#where-the-definition-lives).

## Troubleshooting

### A mention doesn’t start work

Confirm the mention is in a new comment rather than an edit, the username matches the factory’s bot exactly, the project is one of the factory’s selected projects, and the **gitlab-bot-mentions** automation is enabled.

### A merge request event doesn’t start work

Confirm an enabled automation includes the **Merge request** trigger and check its project, action, and base-branch filters. Activity authored by Warp’s own service accounts is always ignored.

### Nothing starts work even though GitLab is connected

Your GitLab plan may not include group webhooks (see [Prerequisites](#prerequisites)). Upgrade your GitLab plan to let GitLab trigger runs.

### The bot can’t push a branch or open a merge request

Confirm the target project is one of the factory’s selected projects and the operation is permitted for the Developer role. Pushes to protected branches follow the project’s protection rules.

### Your group isn’t listed when connecting

Only top-level groups you own appear, and a group already connected to another Warp workspace can’t be connected again. If you don’t own the group, ask an owner to establish the connection in Warp.

For the other ways to route work into a factory, see [connecting your factory](/factories/connect-your-factory/).