Overview

The GitLab integration allows customers to

1. Reduce time to resolution by easily checking potentially relevant pull requests ("merge requests" in GitLab) in the context of an incident via PRs overlaid on incident charts.

   

2. Prevent data issues by seeing an impact report with the potentially impacted tables/reports for a pull request via a message from MC-GitLab bot (requires dbt integration).

   

3. Get code change context on tables via reviewing recent pull request history on the asset page.

   

Setup Instructions

Permissions required

When you create the GitLab application for Monte Carlo, select the api OAuth scope.

GitLab defines the api scope as complete read/write access to the GitLab API for the groups and projects available to the authorizing user. Monte Carlo requires this scope because the GitLab integration uses GitLab's API to:

Permission area	How Monte Carlo uses it
Read groups and projects	List the GitLab groups, subgroups, and projects available to the authorizing user so you can choose which projects Monte Carlo should observe.
Read merge request metadata and diffs	Retrieve merge request details, changed files, and diffs so Monte Carlo can show relevant merge requests in incidents, table history, and impact analysis.
Create and delete group webhooks	Register GitLab merge request webhooks for the selected groups so Monte Carlo can receive updates when merge requests are opened, updated, merged, or closed. GitLab requires the authorizing user to be an Administrator or have the Owner role for the group to manage group webhooks.
Write merge request comments	Post or update Monte Carlo impact analysis comments on merge requests when that feature is enabled.

Monte Carlo does not request GitLab sudo, admin_mode, read_repository, or write_repository scopes. The integration uses the GitLab API and does not require Git-over-HTTP repository write access.

Because GitLab's OAuth scopes do not provide a narrower scope that combines read access, group webhook management, and merge request comments, Monte Carlo uses the api scope. To limit access, create the GitLab application at the group level or authorize it with a dedicated GitLab service account that only has access to the groups and projects you want Monte Carlo to observe.

For more information, see GitLab's documentation for OAuth application scopes (https://docs.gitlab.com/integration/oauth_provider/#view-all-authorized-applications) and group webhook permissions (https://docs.gitlab.com/api/group_webhooks/).

1. Start GitLab-MC Integration

Go to https://getmontecarlo.com/settings/integrations. Under “Notifications and collaboration” click “Create” and select “GitLab”.

Specify custom host, if needed. Navigate via the link after “Create a new GitLab application” to GitLab UI.

2. Create GitLab Application

Go to GitLab, in the Applications tab, click on “Add new application” button. Fill out the form and save application:

• Name: <an identifier of the MC integration>
• Redirect URI: https://getmontecarlo.com/auth/callback/gitlab
• Scopes: select “api”

You will need the Application ID and Secret fields from your GitLab app to create the MC integration.

📘

Note on GitLab App Creation Levels

Gitlab application can be created at different levels with different scopes and permission sets. Please choose based on your needs.

• User level
  • url: https://gitlab.com/-/user_settings/applications this is the link MC UI directs to
  • provides access to all the groups/projects that the user can access
  • once the user is disabled/removed, the integration will stop working
• Admin level
  • url: https://{host}/admin/applications/new
  • only available on self-hosted instances
  • the user must have the admin role
  • provides access to all the groups/projects on the instance
• Group level
  • url: https://gitlab.com/groups/{**group**}/-/settings/applications/new
  • the user must choose the group in advance
  • provides access only to the group's project

3. Complete Integration in MC

Go back to MC UI, fill in Application ID and Secret, then hit “Create”.

You should then be navigated to GitLab UI for authorization.

Once authorized, come back to the MC setup UI to select the GitLab projects you want to observe. Pull requests from the selected projects will be displayed in MC UI to help investigate their impact on your tables.

At this point, you will have GitLab PRs show up in MC UI so you can filter the PRs to identify which ones impacted a given table. But to make the integration more powerful, continue with steps below.

4. [Recommended] Supercharge with dbt integration

MC can map pull requests to the tables they update via the dbt integration. If you want PR-to-impacted table mapping in the UI or impact reports for PRs during CICD, make sure to set up dbt integration following docs.

If you have dbt cloud, then once you set up the dbt integration above you are all set, since all mapping will be done automatically. If you have dbt core, then go to “Configure dbt projects” under the GitLab integration setting to complete the final step.

Under “Configure dbt projects”, you will see a list of dbt connections you set up in MC. Most customers will have just one. For each dbt connection, you will be able to select the dbt project you want to map, then add the project's remote URL and subdirectory. This helps MC point each dbt project at the relevant Gitlab repository, so we can map each PR to the corresponding dbt model and tables.

• Gitlab project remote URL: this should be in the format of https://gitlab.com/<org>/<repo> or git://gitlab.com/<org>/<repo>.git
• Project subdirectory: This is the root directory of the dbt models within the repo. It is only needed if the dbt project is further down the directory. For example, if a model path is analytics/models/foo/bar.sql then subdirectory would be analytics. If a model path is models/foo/bar.sql then subdirectory would be empty.

Press “Update” once done, and you should be all set. Now you will be able to enjoy all the features listed above.