---
title: GitLab
slug: gitlab
docTags: 
createdAt: 2021-08-23T14:52:38.000Z
---

# Purpose

GitLab integration is very similar to GitHub's integration in its purpose.

# Installation

Echoes supports both the [hosted version of GitLab](#) or on-premises deployments.

### Connecting to your GitLab instance

Echoes lets your connect to your GitLab instance either with the **OAuth flow** or using a **Personal Access Token**. There are no security advantage to either method of authentication. OAuth will generally require less clicks and is easier to setup.

::Image[]{src="https://api.archbee.com/api/optimize/cnN9HGi_h1eJLSFAvJkF4/eblPPi9J9epUJTTnaGz1Q_screenshot-2023-09-25-at-153030.png" size="50" width="1002" height="1488" position="center" caption="Connect o GitLab" alt="Connect o GitLab" showCaption="true"}

:::hint{type="success"}
### Using a dedicated service account

We recommend creating a service account on your GitLab instance and installing Echoes under this account's identity.

- It will make the Echoes installation independent of the lifetime of any particular individual. For example, Echoes will continue working properly if the person who did the installation leaves the company.
- It will also allow for fine-grained management of the role under which Echoes operates and the GitLab groups Echoes is allowed to participate in.
:::

### Permissions

The GitLab integration requires the `api` and `read_user` [token scopes](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#personal-access-token-scopes). At installation time Echoes will subscribe to events on your GitLab projects by [registering a webhook](https://docs.gitlab.com/ee/api/projects.html#add-project-hook), which requires **Maintainer** role on the group. 

:::hint{type="info"}
### Proxying the GitLab API

Some customers may be concerned granting the `api` permissions to a third party. For them, we provide a [GitLab API proxy](docId\:sHOXeKu_YlFkDAt7bfHSt) which significantly improves the security guarantees at the cost of self-hosting an additional service.
:::

# Checking for labels

We distribute a [reusable GitLab job](https://gitlab.com/echoeshq/echoes-gitlab-job) you can use in your pipeline in order to check for the presence of Echoes required labels.

:::CodeblockTabs
Diff

```yaml
+ include: https://gitlab.com/echoeshq/echoes-gitlab-job/raw/main/echoes-check.yml

stages:
  - deploy
+ - echoes:check

deploy-job:      
  stage: deploy
  script:
    - echo "Application successfully deployed."
```
:::

Echoes checks that pull requests have at least one `echoes/intent` or `echoes/initiative` label, and *optionally* one `echoes/effort` label. The "details" links has useful documentation to help communicating engineers the purpose of these labels.

Please not that we are closely following GitLab developments for a first-class [Checks API](https://gitlab.com/gitlab-org/gitlab/-/issues/22187) and will integrate with it as soon as it becomes generally available.

# Manage your installations

## Update the Personal Access Token

A **GitLab** integration **installed** with a **Personal Access Token** can be edited.

The edition allows updating the **Personal Access Token **itself. To do so, click on the "three dots" menu under **Actions **->** Edit.**

![](https://api.archbee.com/api/optimize/cnN9HGi_h1eJLSFAvJkF4/lOWYVL5xD8ixXEa6GQV_-_edit-gitlab-installation.png "GitLab installation - Edit")

::Image[]{src="https://api.archbee.com/api/optimize/cnN9HGi_h1eJLSFAvJkF4/C2DWyMKV5HLNqDfsVs0Mj_screenshot-2021-10-08-at-155754.png" size="48" width="1026" height="642" caption="Edit the Personal Access Token" position="center" showCaption="true"}

Once the Personal Access Token is entered** click Save.**

:::hint{type="info"}
Editing the **Personal Access Token **permits for instance to rotate the token for security reasons.
:::

## Update the Repositories

Within the `Repositories` tab is the repositories editor. From this editor it is possible to add or remove repositories from Echoes supervision. When a repository is unselected, Echoes no longer listen to its events.

![Repositories update](https://api.archbee.com/api/optimize/cnN9HGi_h1eJLSFAvJkF4/nrwXys7Vio6CDMUlLvv-a_screenshot-2023-09-25-at-153801.png "Repositories update")

# FAQ

## During the installation, why don't I see my Group in the list?

There are two possible reasons:

- Echoes requires you to be the [Maintainer](https://docs.gitlab.com/ee/user/permissions.html#group-members-permissions) of the Group. Please make sure you are at least the **Maintainer** of the **Group** you are looking for.
- By design Echoes only lists the **top** **Groups. **Therefore Subgroups will not be shown in the list.

##