Gitlab Integration Setup

Getting started

BalkanID recommends creating a service account for this integration rather than using a personal access token tied to an employee account. A service account is a robot user owned by your group, so the integration keeps working when people change roles or leave, and its permissions are managed from the group's Members page like any other member.

To configure GitLab, you will need to be an Owner on the GitLab group you want BalkanID to read.

Choose the role for the service account

The service account's role in your group decides how much BalkanID can see. Both options below give you a complete access review of your users, groups and projects — the difference is whether BalkanID can also inventory your credentials.

	Guest	Owner
Users, groups, projects and who has access to what	Yes	Yes
Security insights (expired memberships, blocked accounts with access, public projects)	Yes	Yes
Access tokens, deploy tokens and deploy keys	No	Yes

Guest is the least-privilege option and is what most organisations start with. The service account can read your group structure and memberships and nothing else.

Owner additionally lets BalkanID list the machine credentials that hold access to your groups and projects. This matters because a token or deploy key is often the most privileged thing in a repository and is rarely reviewed. Note that the role controls what the service account can see, while the token's scope controls whether it can change anything — with the read_api scope below, an Owner-role service account is still strictly read-only. It cannot change members, settings or code.

Create a service account in GitLab

1. Sign in to GitLab as an Owner of the top-level group you want BalkanID to read, and go to that group.

2. In the left sidebar, select Settings > Service accounts.

1. Select Add service account, give it an identifiable name such as BalkanID Integration, and create it. GitLab generates the underlying username and a @noreply email address for you.

2. On the service account you just created, select Add token and fill in:

   1. Token name — something identifiable, for example balkanid-integration.

   2. Expiration date — set a reminder to rotate the token before this date, because the integration stops syncing the day it expires.

   3. Scopes — tick read_api only. BalkanID never writes to GitLab.

3. Copy the token now. GitLab shows it once and will not display it again. If you lose it, revoke the token and add a new one.

4. Give the service account access to your group. Go to Manage > Members > Invite members, search for the service account, and assign the role you chose in Choose the role for the service account — Guest or Owner.

This step is what grants the access; creating the service account on its own gives it nothing. Add it to your top-level group so the whole group tree is covered in one go.

Configure GitLab with your BalkanID tenant

1. Log in to the BalkanID application and switch to the tenant you would like to add your integration to.

2. Head to Integrations > Add Integration, and select GitLab.

1. Set up the Primary Application Owner (mandatory) and the Description, if any. Set up Secondary Application Owner(s), if any.

   Under Direct Configuration, fill in:

   1. Access Token — the group access token you copied above.

   2. GitLab URL — leave as https://gitlab.com for GitLab SaaS. For a self-managed instance, enter its base URL, for example https://gitlab.yourcompany.com.

   
2. Click Next to move on to Optional Configuration.

3. Fill in the remaining optional configuration, if required.

1. Once you have filled in the information, click Save. Your integration is now configured, and you will see its status displayed alongside your other integrations on the Integrations page. When data is available, the integration Status will read Connected and the Message will read Data available.

Adding credentials to an existing integration

If your integration is running with a Guest-role token and you now want your GitLab credentials included:

If you used a service account, no new token is needed. Go to Manage > Members on the group, find the service account, and change its role from Guest to Owner. The existing token picks up the new permission on the next sync.