# GitLab

{% hint style="info" %}
The GitLab integration is in Alpha. Please reach out to your customer success manager or to <hello@swarmia.com> to get access.
{% endhint %}

## Installation

### GitLab Server

{% hint style="info" %}
If you are using <https://gitlab.com> to access GitLab, follow the GitLab Cloud instructions instead.
{% endhint %}

#### Step 1: Create OAuth app

First, you need to create an OAuth application for the Swarmia integration in your GitLab Server. From a permissions perspective it doesn't matter where you create this app, but we recommend that you create it either in the Admin area or then in the top level Group that you want to import to Swarmia (this way the app won't accidentally get deleted).

Create the app with these settings:

* Name: Swarmia
* Redirect URI: <https://app.swarmia.com/auth/gitlab/install/callback>
* Scopes: `read_api`

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

After creating the app, note down the app ID and the app secret, you'll need those later.

#### Step 2: Create a service account user

Create a new user in your GitLab server that will act as the service account for the Swarmia integration. We strongly recommend that you use a dedicated user for this to properly control the access rights and so the user doesn't get deleted when an employee leaves the company etc.

Then, give that user access to all the groups & projects that you want to see in Swarmia. Ensure that the user has at least `Reporter` role in all projects you want to track.

{% hint style="info" %}
GitLab also has a dedicated feature called Service Accounts, which we do not mean here. The Swarmia integration requires a real GitLab user as Service Accounts can't authorize OAuth applications.
{% endhint %}

Make sure to check the "External" checkbox if you don't want to automatically grant access to all projects in your server:

<figure><img src="/files/1p2S7stcbd1awuJeoZHk" alt=""><figcaption></figcaption></figure>

#### Step 3: Add the OAuth app details to Swarmia

First, ensure that in GitLab you are logged in to the service account. You will be authorizing the app in this step.

Then, navigate to the [integration settings page](https://app.swarmia.com/settings/version-control) in Swarmia and click on Connect -> Connect GitLab Server.

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

Fill in the details of the app you created, and then click on Connect, which will take you to GitLab to authorize us to have access to your server via that OAuth app.

After authorizing, you will be redirected back to Swarmia and you should get a popup about setting up webhooks (see Step 4).

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

#### Step 4: Add webhooks

Due to the OAuth app having limited permissions, you will need to manually manage the webhook settings in GitLab.

Add group level webhooks to each top level group whose projects you are interested in seeing in Swarmia, with this configuration:

* URL: <https://hook.swarmia.com/GitlabWebhook>
* Secret token from the modal in Swarmia
* Trigger
  * Push events (All branches)
  * Comments
  * Member events
  * Project events
  * Subgroup events
  * Merge request events

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

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

#### Step 5: Configure your firewall

If your GitLab Server is behind a firewall you’ll need to allow Swarmia's IP address so we can perform GitLab API calls and receive webhooks.

* Inbound IPs (we make HTTPS requests to your GitLab instance): `34.89.165.89` & `35.234.103.84`
* Outbound IPs (GitLab makes HTTPS requests to us): `34.117.202.112` (hook.swarmia.com) & `34.107.207.241` (app.swarmia.com)

If you are unable to grant the inbound traffic access, you can use our [proxy agent](/settings/integrations/proxy-agent.md) to facilitate access.

### GitLab Cloud

{% hint style="info" %}
If you are *not* using <https://gitlab.com> to access GitLab, follow the GitLab Server instructions instead.
{% endhint %}

#### Step 1: Create a service account user

Create a new user in your GitLab server that will act as the service account for the Swarmia integration. We strongly recommend that you use a dedicated user for this to properly control the access rights and so the user doesn't get deleted when an employee leaves the company etc.

Then, give that user access to all the groups & projects that you want to see in Swarmia. Ensure that the user has at least `Reporter` role in all projects you want to track.

{% hint style="info" %}
GitLab also has a dedicated feature called Service Accounts, which we do not mean here. The Swarmia integration requires a real GitLab user as Service Accounts can't authorize OAuth applications.
{% endhint %}

#### Step 2: Authorize the app

First, ensure that in GitLab you are logged in to the service account. You will be authorizing the app in this step.

Then, navigate to the [integration settings page](https://app.swarmia.com/settings/version-control) in Swarmia and click on Connect -> Connect GitLab Cloud. You will be redirected to GitLab, where you need to authorize our access to your instance via our Cloud OAuth app (which requests the `read_api` permission).

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

After authorizing, you will be redirected back to Swarmia and you should get a popup about setting up webhooks (see Step 4).

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

#### Step 3: Add webhooks

Due to the OAuth app having limited permissions, you will need to manually manage the webhook settings in GitLab.

Add group level webhooks to each top level group whose projects you are interested in seeing in Swarmia, with this configuration:

* URL: <https://hook.swarmia.com/GitlabWebhook>
* Secret token from the modal in Swarmia
* Trigger
  * Push events (All branches)
  * Comments
  * Member events
  * Project events
  * Subgroup events
  * Merge request events

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

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

## Permissions

The GitLab permissions granted to Swarmia are a combination of the OAuth app scopes and the authorizing user's access rights. The way to limit Swarmia's access to your projects is to limit the access of the user that you will use to authorize Swarmia with.

Unfortunately, the OAuth app scopes on GitLab's side are very broad. We work with the lowest possible permission scope: `read_api`. This grants us access to most API endpoints that do not write data.

For the authorizing user's permission, we require that the user has at least the `Reporter` role in the projects that you want Swarmia to have access to. You can refer to the GitLab docs [here](https://docs.gitlab.com/user/permissions/) to see what that role grants access to.

### Example

Let's say that you have this organization setup in GitLab:

* Group A
  * Group AA
    * Project 1
  * Group AB
    * Project 2
* Group B
  * Group BA
    * Project 3

You create a new service account for the Swarmia integration, and add it to Group A. After installing the Swarmia app with that service account, we will have API access to all the projects in Group A, but not in Group B. The same logic works at any level of the group hierarchy.

### Webhooks

The webhook permissions are fully in your control. If you create webhook configuration on a Group / Project, we will get all configured events from that regardless of what access the service account has.

### Source code access

We never fetch your source code and thus also do not store it. However, due to how the GitLab API works, we do technically have API access to some pieces of your source code.

The requested `read_api` scope does not have access to most API endpoints that read source code. The one exception is that we are able to see the diffs of *merge requests*. But we are not able to e.g. fetch files directly from the repository or to see diffs of *commits*.


---

# Agent Instructions: 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:

```
GET https://help.swarmia.com/settings/integrations/code-hosting-platforms/gitlab.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.