Last updated Jun 8, 2022

Rate this page:

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 currently supports GitLab 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

Integrate Compass with GitLab

To integrate Compass with GitLab, 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.

Before you begin

  • 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:

  1. Select Apps from the top navigation bar in Compass.
  2. Select Install on the GitLab app card. This installs the GitLab app in Compass.
  3. Select Configure on the GitLab app card.
  4. Authorize the GitLab app to access Compass on your behalf if you haven't previously done so.
  5. Enter the group access token and access token name from GitLab. The access token name must match the name used in GitLab.
  6. 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:

  1. In GitLab, select the project where you want to change the tracking branch.
  2. On the right sidebar select Settings.
  3. Select CI/CD and find Variables in the list.
  4. Click on the Expand button and add the variable.
  5. 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:

  1. In Compass, from the top navigation bar, select Apps.
  2. Select Configure on the GitLab app card.
  3. 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:

  1. In Compass, from the top navigation bar, select Apps.
  2. Select Configure on the GitLab app card.
  3. 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.

Rate this page: