GitLab
How to integrate your GitLab Server or GitLab Cloud instance to Swarmia and what permissions are required.
Installation
GitLab Server
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
After creating the app, note down the app ID and the app secret, you'll need those later.
Step 2: Create a service account
Next, 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 Guest role in all projects you want to track.
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 in Swarmia and click on Connect -> Connect GitLab Server.
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).
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:
Secret token from the modal in Swarmia
Trigger
Push events (All branches)
Comments
Member events
Project events
Subgroup events
Merge request events
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.84Outbound 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 to facilitate access.
GitLab Cloud
Step 1: Create a service account
Next, 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 Guest role in all projects you want to track.
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 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).
After authorizing, you will be redirected back to Swarmia and you should get a popup about setting up webhooks (see Step 4).
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:
Secret token from the modal in Swarmia
Trigger
Push events (All branches)
Comments
Member events
Project events
Subgroup events
Merge request events
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 Guest role in the projects that you want Swarmia to have access to. You can refer to the GitLab docs here 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.
Last updated
Was this helpful?