website logo
Sign upLogin
⌘K
πŸš€ Getting started
Introduction
Echoes fundamentals
Understanding Echoes data
Developer guide
Configuration guides
βš™οΈ CONFIGURATION
Outcomes
Initiatives
Members
Teams
πŸ”Œ INTEGRATIONS
Source code managers
Issue trackers
Incident management
Compatibility matrix
πŸ“Š REPORTS
Organization health
DORA metrics
πŸ€– API
Introduction
Authentication
Releases
Incidents
Efforts
Teams
πŸ”” NOTIFICATIONS
Email report
Slack notifications
πŸ‘€ ACCOUNT
Users & Roles
Single sign-on
Linking identities
Billing
πŸ₯· ADVANCED
Echoes IP addresses
Scoped publishing
Changelog
Docs powered byΒ archbeeΒ 
17min

GitLab

Purpose

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

GitLab Premium (or above) is required

Echoes relies on Group Hooks which is a feature of GitLab Premium and above.

Installation

Echoes supports both the hosted version of GitLab or on-premises deployments.

Prerequisites

Echoes relies on Group Hooks which are a feature of GitLab Premium and above. You can verify if the feature is available in the "Webhooks" settings of your group.

Example of a GitLab group lacking support for group webhooks
Example of a GitLab group lacking support for group webhooks

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.

GitLab integration dialog
GitLab integration dialog

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. At installation time Echoes will subscribe to events on your destination GitLab groups by registering a webhook, which requires Owner role on the group. During normal operations, Echoes however requires no additional permissions than those provided by the Developer role. When Echoes it installed under the identity of a service account, it is therefore safe to downgrade the role of the service account from Owner to Developer once the setup is complete.

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 which significantly improves the security guarantees at the cost of self-hosting an additional service.

Checking for labels

We distribute a reusable GitLab job you can use in your pipeline in order to check for the presence of Echoes required labels.

Diff
|

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 and will integrate with it as soon as it becomes generally available.

Manage your installations

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.

GitLab installation - Edit
GitLab installation - Edit
Edit the Personal Access Token
Edit the Personal Access Token

Once the Personal Access Token is entered click Save.

Editing the Personal Access Token permits for instance to rotate the token for security reasons.

FAQ

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

There are three possible reasons:

  • Echoes requires to GitLab Premium (or above). Therefore make sure the Group you are looking for is not on the Free plan.
  • Echoes requires you to be the Owner of the Group. Please make sure you are the Owner of the Group you are looking for.
  • By design Echoes only lists the top Groups. Therefore Subgroups will not be shown in the list.

ο»Ώ

Updated 26 Oct 2022
Did this page help you?
Yes
No
UP NEXT
GitLab API proxy
Docs powered byΒ archbeeΒ 
TABLE OF CONTENTS
Purpose
GitLab Premium (or above) is required
Installation
Prerequisites
Connecting to your GitLab instance
Using a dedicated service account
Permissions
Proxying the GitLab API
Checking for labels
Manage your installations
FAQ
During the installation, why don't I see my Group in the list?