> For the complete documentation index, see [llms.txt](https://docs.arnica.io/arnica-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.arnica.io/arnica-documentation/getting-started/scm-integrations/gitlab.md).

# Gitlab

## Ensure service account continuity <a href="#h_899746cec5" id="h_899746cec5"></a>

### Create a dedicated application user <a href="#h_729a2d46f2" id="h_729a2d46f2"></a>

Arnica's GitLab integration leverages a GitLab generated app password tied to a specified user. To avoid the revocation of this token upon the impersonated user's departure, it is highly recommended to create and integrate using a standard application user.

{% hint style="warning" %}
The created user will be visible to all developers as part of Arnica's interactions, such as comments on merge requests. Hence, it is recommended to name the service account properly, such as `arnica-service-account`
{% endhint %}

## Prerequisites

### Grant permissions to application user

1. Login to GitLab. Under **Your Work**, click **Groups**, then click on the required group.
2. In the left sidebar, expand **Manage** and click **Members** (or navigate directly to `https://gitlab.com/groups/[YOUR_GROUP]/-/group_members`).
3. Click **Invite members**, enter the username or email of the service account, set the role to **Owner**, and click **Invite**.

<figure><img src="/files/LZ0QEDZKAWZX0o7nSx54" alt=""><figcaption></figcaption></figure>

4. Accept the invite from the service account.

{% hint style="warning" %}
If your environment is comprised of multiple groups, repeat the steps above for each group with the same user.
{% endhint %}

## Integration process

### Generate a Personal Access Token

1. Login with the application user and navigate to the [Personal Access Tokens page](https://gitlab.com/-/user_settings/personal_access_tokens).
2. Give the token a name and **leave the expiration date blank** (no expiration).
3. Enable the following scopes:

| Scope              | Purpose                                                          |
| ------------------ | ---------------------------------------------------------------- |
| `read_repository`  | Read access to repositories                                      |
| `read_registry`    | Read access to container registry images                         |
| `read_api`         | Read access to the API, groups, projects, and package registry   |
| `write_repository` | Write access to repositories via Git-over-HTTP                   |
| `api`              | Full API access including groups, projects, and package registry |

<figure><img src="/files/kDi78lFbsq7NCileXvJ4" alt=""><figcaption><p>Leave the expiration date blank and enable the required scopes</p></figcaption></figure>

4. Click **Generate token**.
5. Copy the token — you'll need it in the integration step below.

### Integrate with Arnica

1. Navigate to the [Integrations page](https://app.arnica.io/#/admin/integrations) in Arnica and click on `GitLab`.
2. Click on the `Access Token` tab.
3. Fill in the token from the step above.
4. Click on `Validate` to ensure that the token works properly and then click on `OK`.

{% hint style="info" %}
Arnica will integrate with all groups associated with this user. Arnica's default policies include scan-only functionality. While scanning will begin immediately, developers will not see any impact until Arnica's polices are updated to take actions.
{% endhint %}

## Token lifecycle and troubleshooting

### Re-integrating after token expiration

If the existing GitLab token expires, create a new Personal Access Token with the same required scopes and update the GitLab integration in Arnica.

### Validation passes but integration behavior is incomplete

If validation succeeds but groups, webhooks, or scans are missing:

* Confirm the service account has **Owner** access on the top-level GitLab group.
* Confirm the PAT includes the required API scopes.
* Confirm the same account is granted access in each additional GitLab group you want Arnica to cover.

### Service account usage

Dedicated service accounts are supported and recommended for continuity. This prevents integration disruption when individual employees leave or rotate access.


---

# 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.arnica.io/arnica-documentation/getting-started/scm-integrations/gitlab.md?ask=<question>&goal=<endgoal>
```

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