> For the complete documentation index, see [llms.txt](https://docs.balkan.id/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integration/gitlab-integration-setup.md).
# 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**.
3. 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.
4. 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.
5. **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.
6. 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**.
3. 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`.
4. Click **Next** to move on to **Optional Configuration**.
5. Fill in the remaining optional configuration, if required.
6. 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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integration/gitlab-integration-setup.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.