Integrate Compass with 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
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.
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.
Monorepos
We recommend you create a component which represents the entire monorepo and then additional components to represent each part of (or the packages/modules within) the monorepo.
The GitLab integration will capture all activity (events, metrics) across the entire monorepo regardless of the path you enter for the repository URL. You can change this behavior by navigating to a component detail page, select more actions (), then Component of a monorepo, and enable this setting.
This will stop the GitLab integration from collecting and processing repository activity for this component. Disabling the setting will connect the component back to GitLab and Compass will backfill activity for the last 28 days.
To get accurate events and metrics for each of the components within a monorepo after enabling this setting, you should use our API:
Enabling the Component of a monorepo setting will delete any existing data (events, metrics) for builds, deployments, and pull requests collected by the GitLab integration for the component.
Creating monorepo components with GraphQL
If you're creating components using the GraphQL API, you can set the isMonorepoProject field to true or false to control the "Component of a monorepo" setting with the createComponent mutation.
Was this helpful?