---
url: https://clusto.app/docs/gitlab.md
description: >-
  GitLab accounts - connect gitlab.com or a self-managed GitLab on a host node,
  poll a group's projects and open merge requests with their pipeline status,
  and mark a factory account the software factory opens merge requests with.
---

# GitLab

A **GitLab account** connects Clusto to gitlab.com or a self-managed GitLab
instance. One host node holds the account's token and polls GitLab: the projects
of the account's group (subgroups included) and their open merge requests, each
with the status of its head pipeline. The software factory uses a **Factory**
GitLab account to open merge requests in that group. There is no GitLab view in
the app yet; Settings shows each account's token status, what the last poll found
and any error. GitLab accounts are free on every plan.

::: tip Early access
GitLab accounts ship behind the `gitlab.accounts` release flag, which is off by
default. Turn it on in **Settings -> Labs**. The flag only shows or hides the
**Settings -> GitLab** tab; accounts saved earlier keep polling either way. See
[Feature Flags](/feature-flags).
:::

## Set up

1. Open **Settings -> GitLab** and press **Add GitLab account**.
2. Fill in the fields:
   * **Name**: a label for the account.
   * **Host node**: the node that polls GitLab and holds the token. Pick a node no
     agent can read: the token can write to every project it covers.
   * **GitLab URL**: keep `https://gitlab.com`, or enter your self-managed
     instance (`https://gitlab.example.com`, a path prefix is fine). Plain `http://`
     is accepted only for a loopback host, such as a local test instance.
   * **Group**: the full path of the top-level group or user namespace the account
     works in (`acme` or `acme/platform`). Subgroups are included. Leave it empty on
     a Browse account to list the projects you are a member of. A Factory account
     needs it.
   * **Purpose**: **Browse** only polls. **Factory** marks the account the
     software factory may use, and only inside its group.
   * **Poll interval**: 30 to 3600 seconds (default 120).
   * **Squash commits by default**: the merge default the factory uses.
3. Press **Create token in GitLab**. It opens your instance's personal access
   token page with the name `Clusto` and the `api` scope filled in. Create the
   token, paste it into **Personal access token** and press **Save**.

The host checks the token with GitLab before saving it and shows the user it
authenticates as. For a Factory account, use a dedicated bot user (or a group
access token) that is a member of the factory's group only.

## Factory accounts

A Factory account lets the [software factory](/factory) open merge requests in
the account's group. Repositories are written `group/.../project` and must sit
inside the account's **Group**; anything outside it is refused. The factory
labels each merge request with its risk tier, reads head pipelines and failed
job traces, retries failed jobs once before a fix attempt, and merges with the
expected head commit. The factory runs from the same Factory account on the
host node; the token never reaches the agent. See [Software factory](/factory)
for the repository files and the item flow.

## What the host polls

* **Projects**: the group's projects and those of its subgroups, or the projects
  of a user namespace, read again every 10 minutes and whenever you save the
  account or press **Refresh**. Archived projects are listed as archived.
* **Open merge requests**: one request for the whole group. For a user namespace
  or a member-projects account, the 30 most recently active projects are read one
  by one.
* **Pipelines**: the newest pipeline of each merge request's head commit, up to
  40 per poll. A finished pipeline is not read again until the head commit
  changes.

When GitLab rejects the token (`401`), polling backs off from 2 minutes up to 30
minutes until you save a new token. When GitLab rate-limits, the host waits as
long as GitLab asks.

## Token security

* The token lives only in the host node's config (`[gitlab]` section). It is
  never replicated to other nodes, never sent back to any app and never written
  to logs. The account list itself is shared across the cluster.
* The token is pinned to the GitLab URL it was checked against. If the account's
  URL changes, the host stops using the token and asks for it again, so a changed
  URL can never send the token to another server.
* Moving the account to another host node or removing it deletes the token from
  the old host.
* Setting or removing a token is recorded in the node's audit log, without the
  token.

## Troubleshooting

* **No token**: the host has no token for the account, or the account's URL
  changed since it was saved. Paste a token and save.
* **GitLab rejected the token**: it expired, was revoked or lacks the `api`
  scope. Create a new one.
* **Could not read the GitLab group**: the group path is wrong, or the token's
  user is not a member of it.