Skip to main content

GitLab

GitLab supplies the repository, issues, and merge requests Factory works with, as an alternative to GitHub.

Platform-backed servers connect GitLab through Mastra Platform. Servers with their own access token can use the self-managed configuration.

Connect the repository​

Connect a GitLab account before selecting a repository. On a Platform-backed server, connect GitLab in Mastra Platform, then return to Factory.

When you create a Factory, choose GitLab as the repository provider and select the project agents should change. The provider list always offers GitLab: with no connection or access token configured yet, it shows Connect GitLab and opens Mastra Platform to connect an account. When the server has its own access token, Factory uses that token instead.

Factory clones the repository and pushes session branches through the connected credential. The credential needs write access to the selected project.

Select your issue intake​

  1. Open Settings → Work Intake.
  2. Under GitLab issues, enable Sync GitLab issues.
  3. Select the projects you want to follow. Projects are grouped by connected account.
  4. Wait for Intake sources updated, then return to Work.

Under GitLab routing, choose the destination Factory and board for each selected project. Each project supplies one board in one Factory. Until a project is fully routed, its issues aren't picked up.

Selections are shared across the organization: every member sees open issues from the selected projects. Factory brings merge requests from your linked repository into Review. See Review items.

If issues don't appear in Factory, read Troubleshooting.

Use your own access token​

Direct deployments authenticate with a GitLab Personal Access Token or Group Access Token. Both authenticate the GitLab API and Git-over-HTTPS the same way. They differ in reach: a personal token follows the user's accessible projects, while a group token is limited to its group and subgroups. Create the token with the api and write_repository scopes. Factory uses them to manage issues and merge requests, and to clone repositories and push session branches. See GitLab's personal token and group token documentation.

Set the token on the Factory Server and restart it:

.env
GITLAB_ACCESS_TOKEN=your-gitlab-access-token
GITLAB_ACCESS_TOKEN_TYPE=personal # Or group.
GITLAB_BASE_URL=https://gitlab.example.com # Omit for gitlab.com.
GITLAB_WEBHOOK_SECRET=your-webhook-secret # Optional, enables the direct webhook.

GITLAB_BASE_URL must use HTTPS. Plain HTTP is accepted only for loopback development instances, where the access token is sent without transport encryption.

The generated entry uses this explicit integration when the access token is present, taking precedence over a Platform connection.

Webhook delivery​

With GITLAB_WEBHOOK_SECRET set, point the GitLab project webhook at your public origin plus /web/gitlab/webhook, using the same value as the secret token.

On a Platform-backed connection, issue, note, merge request, and push events reach Factory by polling the Platform event log instead. Point the project webhook at the Platform's forwarding URL, not at Factory. Don't point a project webhook at both Factory and the Platform, or each event is processed twice.