---
description: Using GitLab to create study groups and projects.
---

# GitLab

Study Tracker supports integration with GitLab cloud or Community Edition (aka. Omnibus) via its REST API. Once configured, users can choose to create Git repositories to be linked to their studies, so that computational workflows and source code can be captured.

### Preparing GitLab for Study Tracker Integration

Study Tracker will use a single GitLab project for creating study repositories. A single sub-group will be created for each Study Tracker program, under which projects (aka. Git repositories) will be created for both studies and assays. It is best that you start fresh with an empty group and use it exclusively for Study Tracker-created repositories.

#### Create a new Group in GitLab.&#x20;

This needs to be done by an administrator. Give your project a clear name. Be thoughtful about how you set the Visibility Level of the group. For private GitLab instances, to ensure that projects are accessible to colleagues who do not have GitLab licenses, you should set the Visibility Level of the group 'Public'. For hosting on GitLab cloud, it is probably not wise to make your study projects available to the public internet.

<figure><img src="https://157675233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWzxr1lQXVcdFuqP1WfyV%2Fuploads%2FBMJYHX0oEOkFuxpSje9L%2Fimage.png?alt=media&#x26;token=55f1df98-84c1-4957-8dd2-9687e7083c1c" alt=""><figcaption></figcaption></figure>

<figure><img src="https://157675233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWzxr1lQXVcdFuqP1WfyV%2Fuploads%2FZZjo6gAXjSOFycOQGr4j%2Fimage.png?alt=media&#x26;token=9d5056b7-41e7-4fc1-800d-f149a44956de" alt=""><figcaption></figcaption></figure>

Once the group has been created, make a note of the 'Group ID' that is displayed on the summary page.

<img src="https://157675233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWzxr1lQXVcdFuqP1WfyV%2Fuploads%2FQAobDkjv9rokRUpWTn8y%2Fimage.png?alt=media&#x26;token=b0f1616b-00ef-415f-89fb-eb0cb32bb238" alt="" data-size="original">

#### Create an Access Token

Once the group has been created, you need to allow Study Tracker to access it using the GitLab API. The simplest way to do this is with a [Group Access Token](https://gitlab.internal.vesaliustx.com/help/user/group/settings/group_access_tokens), which can be created in the group settings menu by someone with the appropriate privileges. The access token should be granted the 'Maintainer' role and 'api' scope, allowing it to create and access subgroups and projects.

{% hint style="info" %}
It is possible to configure GitLab-Study Tracker integration with user credentials, but this violates the [Principle of Least Privilege](https://www.cisa.gov/uscert/bsi/articles/knowledge/principles/least-privilege), as it grants Study Tracker potential control of the account being used and the ability to modify groups and projects outside the Study Tracker scope.
{% endhint %}

![](https://157675233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWzxr1lQXVcdFuqP1WfyV%2Fuploads%2FERIHCDvaEfFYvVg7LFFy%2Fimage.png?alt=media\&token=e734d645-9c6c-450a-919e-a77cf648f3bf)

<figure><img src="https://157675233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWzxr1lQXVcdFuqP1WfyV%2Fuploads%2FyHCWZfC68VaYfST16ezV%2Fimage.png?alt=media&#x26;token=238f432e-b65e-42a3-8947-06d0bf0c972f" alt=""><figcaption></figcaption></figure>

The created access token can be used to authorize API requests, without the need to authenticate a user. This is done by passing it in the `Authorization` header with the `Bearer` prefix (eg. `Authorization: Bearer abcd-122324i534i`). Be sure to save this token in a safe place.&#x20;

### Configuring Study Tracker

Once you have configured your GitLab group and generated an access token, you can configure the integration within Study Tracker. If you followed the steps described above, you can add the following parameters to your `application.properties` file:

```
git.mode=gitlab
gitlab.url=https://gitlab.mydomain.com
gitlab.root-group-id=123
gitlab.access-token=abcd-123456789
```

If you prefer to use user credentials to authenticate your GitLab requests, you will have to [enable OAuth](https://gitlab.internal.vesaliustx.com/help/integration/oauth_provider) and [configure an application](https://gitlab.internal.vesaliustx.com/help/integration/oauth_provider#instance-wide-applications) for Study Tracker in your tenant. Once done, you can provide the Application ID and secret token with your user credentials to configure integration with Study Tracker:

```
git.mode=gitlab
gitlab.url=https://gitlab.mydomain.com
gitlab.root-group-id=123
gitlab.client-id=xxxxx
gitlab.client-secret=xxxxxx
gitlab.username=xxxxxx
gitlab.password=xxxxxx
```
