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.

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.

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