Last updated Apr 19, 2024

Integrate Compass with GitLab

What is GitLab?

GitLab is a web-based Git repository that provides free open and private repositories, issue-following capabilities, and wikis. Compass supports GitLab SaaS but not self-managed.

Compass currently supports GitLab SaaS as a tool to:

import components from GitLab projects to track them in Compass
automate component management from an external tool with config-as-code
sync component data, such as deployment activity, from GitLab to Compass
only GitLab.com SaaS/cloud hosted instances are supported, we do not currently support self-managed GitLab instances

Integrate Compass with GitLab

To integrate Compass with GitLab SaaS, you must first install the GitLab app in Compass. Then, you must create and retrieve your GitLab group access token to connect Compass to the GitLab account to finish setup and begin importing components from GitLab and/or managing components via config-as-code.

When you integrate an app with Compass, other Compass users can view events and metrics data sent from the app to Compass, even if they don't have access to that data in the underlying app. For example, when you integrate Bitbucket with Compass, someone who doesn't have access to a repository can see the events and metrics related to that repository in Compass. The same applies to data sent from this app to Compass.

Before you begin

Compass supports GitLab.com SaaS/cloud hosted instances and does not currently support self-hosted GitLab instances.
Ensure that you’re an owner of the GitLab account you want to connect to or work with your account owner to install this GitLab app.
Ensure that you’re an admin on your Compass instance.

You can connect only one GitLab group to a Compass instance.

Perform the integration

Create and retrieve your GitLab group access token: When creating your group access token, make sure you:

do not set expiration date, leave it empty
set required scopes for the token to “api” and “write_repository”
select an owner role for the token
have GitLab owner permissions for the group you want to connect

Learn more about group access tokens

Integrate Compass with GitLab:

Select Apps from the top navigation bar in Compass.
Select Install on the GitLab app card. This installs the GitLab app in Compass.
Select Configure on the GitLab app card.
Authorize the GitLab app to access Compass on your behalf if you haven't previously done so.
Enter the group access token and access token name from GitLab. The access token name must match the name used in GitLab.
Select Connect group.

Now you can manage components from the repositories within the connected GitLab project by setting up configuration as code (config-as-code) for your components. Learn how to manage components via config-as-code.You can also import GitLab components from GitLab into Compass. Learn how to import components from GitLab

Add non-default branch (optional)

You can track changes from another branch instead of your project's default branch. This means that new config-as-code files, as well as build events used in calculating metrics such as Build Success Rate, will be tracked for a different branch than the default branch.

Set up a non-default (tracking) branch:

In GitLab, select the project where you want to change the tracking branch.
On the right sidebar select Settings.
Select CI/CD and find Variables in the list.
Click on the Expand button and add the variable.
The variable must be called COMPASS_BRANCH and the value is the name of the tracking branch.

If you delete the COMPASS_BRANCH variable or the tracking branch itself, your default branch will be automatically tracked by compass again.

Disconnect the GitLab project connected with Compass

Compass’s integration with a GitLab project lets you manage your components with configuration as code (config-as-code) by using GitLab as a component management tool. However, if you want to configure a different project or no longer want to use config-as-code, you can disconnect your current GitLab project from Compass.

Before you begin

Ensure that you’re an admin on your Compass instance.

Once you disconnect a GitLab group, any managed components in Compass are disconnected and will no longer be synced with GitLab. Don’t worry, the components remain in Compass and you can manage them via the Compass UI.

Disconnect the project

To disconnect a GitLab account from Compass:

In Compass, from the top navigation bar, select Apps.
Select Configure on the GitLab app card.
Select Disconnect account on the GitLab app card. The GitLab project is disconnected from Compass and the page refreshes to its initial state with no account connected.

Now you can manage the components previously managed via config-as-code from the Compass UI. You can also configure a different GitLab organization.

Uninstall the GitLab app from Compass

If you no longer want to use GitLab as a component management tool, you can uninstall the GitLab app from Compass.

Before you begin

Ensure that you’re an admin on your Compass instance.

Once you uninstall the GitLab app, any managed components in Compass are disconnected and will no longer be synced with GitLab. Don’t worry, the components remain in Compass and you can manage them via the Compass UI.

Uninstall the Gitlab app

To uninstall the GitLab app from Compass:

In Compass, from the top navigation bar, select Apps.
Select Configure on the GitLab app card.
Select Uninstall on the GitLab app card. The GitLab app uninstalls from Compass.

Now your GitLab-managed components will no longer be managed by any existing compass.yml files and can be modified and updated via the Compass UI. At any time, you can again integrate Compass with GitLab to set up config-as-code for component management.

Import components from GitLab

Once you have finished setting up the integration, you can import your repositories from GitLab into Compass as components. Simply select Create from the top navigation bar in Compass and then choose "Import components" to get started. Learn more about importing from GitLab here.