Skip to content

Connect GitLab

This page covers the first two checklist items on the workspace Home page: Set the GitLab URL and Add a managed account.

Click Set URL and enter the root URL of your GitLab instance.

  • For GitLab.com: https://gitlab.com
  • For a self-managed instance: the URL you use to access the web UI, for example https://gitlab.example.com

The URL must be http or https. On the hosted service the host must also resolve to a public address (loopback, private-range and similar addresses are rejected). Click Save. You can change the URL later under Settings → GitLab connection, but it is locked while managed accounts exist, because their tokens belong to that GitLab. Remove the accounts first if you need to change it.

Mate acts in GitLab as a dedicated account. Use a dedicated GitLab account for Mate, not your personal one: assigning an issue or merge request to it, asking it for a review or @-mentioning it is what starts a job.

On the GitLab account Mate will use, go to User settings → Access tokens → Personal access tokens and create a token with the api scope. Set an expiry date if your policy requires one, and copy the token before leaving the page.

Click Add account (or open Managed accounts in the sidebar). Paste the token into the GitLab access token field and click Check token. Mate asks GitLab who the token signs in as and shows:

  • the account’s username (taken from GitLab, you never type it),
  • its GitLab state,
  • the token’s scopes, with any missing required scope marked.

If a scope is missing, create a new token that includes it. Otherwise click Add account. Mate encrypts the token at rest; it is not retrievable afterwards. The Add account button is disabled while a required scope is missing.

If the token belongs to an account that is already managed, the console offers Replace its token, which is how you rotate a token. This also works from the Managed accounts page.

  • The account is active in GitLab (not blocked or deactivated); Mate will not add an account that is not.
  • The account is a member of every project you want Mate to work in. Add it via Project → Members in GitLab, with a role that fits what you plan to grant: Reporter to comment, Developer to push branches and open MRs, Maintainer for merge or touch_ci.

Next: LLM credentials