Skip to main content
Kliff
Back

Connect GitLab

Link your GitLab account and connect a group on GitLab.com or your own GitLab so agents and automations can work on its projects.

Connecting GitLab takes two steps, both in Settings > GitLab. Nexus works with groups on GitLab.com and on your own GitLab, if it runs version 19.1 or newer of the Enterprise Edition.

  1. Open Settings > GitLab.
  2. Under Your GitLab account (Your GitLab accounts when your organization uses more than one GitLab), select Link account next to the GitLab you use, and approve the request on GitLab.

The row then shows Connected as your GitLab username. Nexus uses this link to check your role on a project when you start a run or mention @nexus on a merge request or issue. It keeps your GitLab username and id, not a token. If your organization uses more than one GitLab, link your account on each.

How do I connect a GitLab group?

  1. Open Settings > GitLab.
  2. Under GitLab groups, select Connect a group and approve the request on GitLab.
  3. Under Your groups, select Connect next to the group.

Only an organization owner or admin can connect a group, and they need the Owner role on a top-level group on GitLab.com. Nexus adds a service account to the group with the Developer role and lists the group's projects under Projects. After you add projects on GitLab, select Refresh projects to bring the list up to date.

Can I connect my own GitLab?

Yes, when it meets all of these:

  • It runs GitLab 19.1 or newer, Enterprise Edition. The Free tier works; the Community Edition does not, because it has no service accounts.
  • An administrator has turned on Allow top-level group owners to create service accounts in the GitLab Admin area.
  • Its address is a public HTTPS site that Nexus can reach, and it can send webhooks to Nexus over the internet. Nexus cannot reach a GitLab on a private network.

How do I add my own GitLab?

  1. On your GitLab, open the group's Settings > Applications and add an application. Use the callback URL shown under Self-managed GitLab in Nexus, and select the scopes api and read_user.
  2. In Nexus, open Settings > GitLab. Under Self-managed GitLab, enter your GitLab's address and the application's ID and secret, then select Save GitLab.
  3. Select Connect a group next to your GitLab, approve the request on it, and select Connect next to the group.

Only an organization owner or admin can add a GitLab. Nexus keeps the application secret encrypted. If your GitLab is older than 19.1 or not the Enterprise Edition, connecting stops with a message saying so.

What role do I need on a project?

The Reporter role or higher to request a review, and the Developer role or higher to have Nexus make changes. Nexus checks your role each time a run starts.

Who opens the merge requests?

The group's service account. Nexus pushes its branches, opens draft merge requests, and posts reviews as that account, so they appear under its name on GitLab.