NOTE: Datadog's GitLab integration is currently in a closed preview, to request access for your organization please reach out to Datadog Support

This document will guide you through the different elements of configuration to integrate your Datadog account with your GitLab instance or account.

This integration requires configuring:

• Webhooks, to allow Datadog to react to events happening on your GitLab instance or account (e.g. a branch being pushed, or a Merge Request being updated)
• A Service Account, to allow Datadog to access select resources through GitLab’s API
• An OAuth2 application, so that members of your GitLab organization can authorize Datadog to access certain resources on their behalf. (For self-managed instances only)

This integration supports GitLab.com, GitLab Self Managed, and GitLab Dedicated. You must be using either GitLab Premium or GitLab Ultimate (the Free tier is not supported).

NOTE: For Self Managed and Dedicated instances, the integration requires GitLab 16.10 or later.

For the integration to function correctly:

• Your GitLab instance should allow ingress from Datadog servers, so that Datadog can make API calls to your GitLab instance. Datadog’s IP addresses are documented here (use the webhooks section from the API response), access is needed on port 443 (HTTPS).
• Your GitLab instance should allow egress to Datadog servers, so that Datadog can receive webhooks sent by your instance. (See below for the domain name that needs to be allowed, port 443 (HTTPS)).

To setup the integration with Datadog, you’ll need to be:

• GitLab.com: an Owner of the top-level group
• Self Managed / Dedicated: an instance administrator

This guide will need you to perform requests to GitLab’s API, authenticated as a group Owner / Administrator. You’ll need a personal access token with the api scope, which can be generated on:

• GitLab.com: https://gitlab.com/-/user_settings/personal_access_tokens
• Self Managed / Dedicated: https://your-hostname.example.com/-/user_settings/personal_access_tokens

This token is only needed for the initial setup of the integration, and can be revoked once you’ve completed this guide.

You’ll need the Integrations Manage permission in your Datadog organization. You can check if you or another user has this permission enabled by going to the Users page within your Datadog Organization Settings (see links below for your Datadog site):

• AP1
• EU1
• US1
• US3
• US5

Installing the integration will require some calls to Datadog’s API, for which you’ll need an API key and an application key.

Please generate an API key dedicated to the GitLab integration; it will be used by your GitLab instance to authenticate webhooks sent to Datadog, and revoking it will break the integration.

The execution of the scripts in this repository requires the installation of the following packages:

• coreutils
• jq
• curl

Example installation oneliners:

• brew install coreutils jq curl (macOS)
• apt-get install coreutils jq curl (Ubuntu)

For the shell snippets & scripts below, please configure the following environment variables:

Variable name	Value	Example
DD_API_KEY	Datadog API key	***********************285d
DD_APPLICATION_KEY	Datadog Application key	************************************e27b
DD_SITE	Datadog site	datadoghq.com
DD_DOMAIN	Custom datadog domain (if applicable), or the datadog app domain for your site	app.datadoghq.com, us3.datadoghq.com, my-company.datadoghq.com
GITLAB_ADMIN_TOKEN	Your personal access token, as group Owner or instance admin	glpat-AsDf-********
GITLAB_HOSTNAME	Your GitLab instance hostname	gitlab.com, gitlab.my-company.com
GITLAB_GROUP_ID	The ID of the top-level GitLab group (only required for GitLab.com). It can be retrieved from the group homepage:	2400579
ORG_NAME	Your organization name. Only required to uniquely name the service account for GitLab.com groups, which have to be unique on the GitLab instance	ACME Corp

You can configure webhooks at the project, group or instance level by following these instructions. Enabling CI Visibility isn't required here. Be wary that enabling it might impact your Datadog bill.

For these versions of GitLab, webhooks have to be setup manually. Running the following shell snippet will create a webhook on a group, with the following configuration:

• URL: https://webhook-intake.<DATADOG_SITE>/api/v2/webhook
• Headers: DD-API-KEY: <your API key here>
• SSL Verification: Enabled
• Trigger: Push events, Tag push events, Merge request events.

WARNING: Don’t select Pipeline events or Job events, this would enable the CI Visibility product, which has billing implications.

Please run it with a different GITLAB_GROUP_ID for each GitLab group you want to integrate. This uses this GitLab API endpoint

# Registers a group webhook: https://docs.gitlab.com/ee/api/group_webhooks.html
curl -XPOST -f  https://$GITLAB_HOSTNAME/api/v4/groups/$GITLAB_GROUP_ID/hooks \
  -H "PRIVATE-TOKEN: $GITLAB_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{ \
    \"url\": \"https://webhook-intake.$DD_SITE/api/v2/webhook\",
    \"name\": \"Datadog\",
    \"push_events\": true,
    \"tag_push_events\": true,
    \"merge_requests_events\": true,
    \"custom_headers\": [{\"key\": \"DD-API-KEY\", \"value\": \"$DD_API_KEY\"}]
}"

GitLab Service Accounts can only be configured through GitLab’s API. You’ll need to be an Owner of your GitLab.com top-level group, or an administrator of your GitLab Self Managed instance, and generate a personal access token to run the configuration steps.

First, you’ll need to follow the steps here to allow non-expiring tokens to be generated for the Service Account: https://docs.gitlab.com/ee/user/profile/personal_access_tokens#create-a-service-account-personal-access-token-with-no-expiry-date

Please review and run the following script:

./create-serviceaccount-gitlab-com.sh

Please review and run the following script:

./create-serviceaccount-self-managed.sh

You'll then need to add the Service Account with at least Reporter role in the groups and projects that you want Datadog to have access to:

• Click Members in the group panel

• Click the Invite Members button on the top-right

• Look for the Service Account user, and add it with Reporter role. You can find the Service Account name and username in the output of the previous script.

This step is only required for Self Managed & Dedicated. It creates an OAuth2 application on your instance, which will be controlled by Datadog to let your users authorize access to certain resources (e.g. code snippets).

Please review and run the following script:

./create-oauth-app.sh