How the GitLab Datadog integration sends pipeline data to Datadog
An operations or platform team that wants pipeline and job health in Datadog next to its other telemetry does not need a custom connector. The GitLab Datadog integration is a built-in integration that is configured inside GitLab, and it sends CI/CD pipeline and job information to Datadog. It is available in all GitLab tiers, so the choice of edition does not limit it. It can be set at the instance, group or project level, and a setting at a lower level can override the one above it. It can also optionally enable CI Visibility, which Datadog prices per committer, so that decision belongs in a budget conversation before anyone switches it on.
Before configuring anything, confirm three things with Datadog and with your own administrators: which Datadog site and API key the instance will use, which groups and projects should send data at all, and whether CI Visibility is wanted now or later. Keep the initial scope narrow, for example one group with a few representative pipelines, so that the cost of per-committer billing is understood before it applies to the whole organization. Settings at the instance level are the easiest to forget, so record where each value is set and who owns it. DeployOpen plans this scope in writing and verifies the configuration inside your environment, including the Datadog site your organization uses.
Verification should show data arriving in Datadog for the scoped projects, and confirm that nothing sends from projects outside the agreed scope. Check that a test pipeline produces pipeline and job records, and that the optional job log collection is enabled only where your policy allows log content to leave GitLab. The GitLab Datadog integration documentation lists the settings to review. Repeat the check after each GitLab upgrade, because integration behavior and settings can change between releases, and keep the results as part of your change records.
What you need before you configure the Datadog integration
Most delays in this integration happen before anyone opens the GitLab settings page. The cards below cover the GitLab access, the Datadog decisions, the credentials and the network and approval questions that have to be settled first. Work through them in order so the configuration step is a short, predictable change.
A self-managed GitLab instance and the right role
The integration is configured in GitLab itself, at instance, group or project level, so you need a user who can edit the settings at the level you choose. Instance-level settings need an administrator, while group or project settings need an owner or maintainer with the matching permission. Confirm which level your organization will use before you start, because a project-level setting overrides a group default and that choice affects every project that inherits it. The Datadog integration is available in all GitLab tiers, so tier is not the blocker here.
A Datadog account and a CI Visibility decision
Before configuration, decide whether you want only pipeline and job information in Datadog or also CI Visibility, which is the optional layer that Datadog bills per committer. Ask your Datadog account team for the current CI Visibility price and how committers are counted, including whether people who commit to several repositories are counted once. This decision changes the contract, the budget owner and who must sign off, so it should not be made by the engineer who configures the webhook.
A Datadog API key with the required scope
The integration authenticates to Datadog with an API key that must have the permissions Datadog requires for ingesting CI data. Confirm the exact key type, its scopes and whether a service account is recommended in Datadog's current documentation, since those details can change. Create the key under a service identity rather than a personal user, record its owner and rotation schedule, and store it in your secrets manager instead of pasting it into a shared document.
The correct Datadog site for your organization
Datadog runs separate sites, and the API key and endpoint only work against the site where your organization's account lives. Confirm your Datadog site with your platform team before configuration, since a mismatch produces a connection that looks configured but delivers no data. Record the site name alongside the key so that a future site migration or a second Datadog organization does not silently break pipeline reporting.
Network egress from the instance and runners
The GitLab instance sends the integration data, and runners may need outbound access depending on how jobs report to Datadog in your setup. Ask your network team to allow outbound HTTPS from the GitLab application servers and any runner subnets to the Datadog endpoint for your site. Where the instance is offline or behind a strict proxy, confirm the proxy and allowlist rules before you test, because blocked egress is one of the most common reasons the first test fails.
Approval to send pipeline metadata outside the instance
Pipeline and job information can include branch names, job names, commit author details, runner tags and pipeline timing, so it leaves your instance once it is sent to Datadog. Get written approval from the data owner, security team and, where relevant, your compliance function before enabling the integration. Ask the approvers to confirm whether job log collection is in scope, because logs can contain more sensitive content than pipeline metadata and may need a separate review.
Choosing instance, group or project scope for the integration
Instance-level settings are made by administrators of the self-managed GitLab instance and become the default for every group and project that inherits them. This is the widest scope, so it affects the most teams and the largest Datadog billing footprint. Agree the policy with security and finance owners before enabling it.
- Who sets it: instance administrators, once, in the Admin area, with the Datadog connection details entered at that level.
- Which pipelines it covers: every project that inherits the instance default, including projects created after the setting is saved.
- Inheritance: groups and projects below the instance can inherit or override the setting. Confirm in the Datadog integration documentation for your installed version how overrides behave.
- Risk of enabling broadly: pipeline and job data from all teams starts flowing to Datadog at once, and CI Visibility, if enabled, is priced per committer across the whole instance.
Ask Datadog for a committer count that covers every active contributor who would be included before you turn this on at instance level.
Group-level settings are made by group owners and apply to the projects and subgroups beneath that group. They suit a business unit or product line that has its own Datadog account, budget or approval path. Administrators can restrict who may change integration settings, so confirm the permissions on your instance first.
- Who sets it: owners of the group, applied in the group's integration settings.
- Which pipelines it covers: projects in the group and in its subgroups that inherit the group setting.
- Inheritance: subgroups and projects inherit unless they hold their own override. Check the overrides in each project before assuming which projects send data.
- Risk of enabling broadly: a top-level group with many subgroups sends data from teams that have not agreed to it, and committers across all those projects count toward CI Visibility billing.
Map the group's projects and committers against your Datadog agreement before you enable the setting on a parent group.
Project-level settings are made by project maintainers and cover only that project's pipelines and jobs. This is the smallest blast radius and the simplest place to test how data arrives in Datadog. The trade-off is that many projects configured one at a time are harder to audit later.
- Who sets it: project maintainers, in the project's integration settings, which may be limited by group or instance policy.
- Which pipelines it covers: only the pipelines and jobs of that single project.
- Inheritance: a project setting can override a group or instance default, so it governs that project regardless of the level above. Confirm the exact precedence for your version in the documentation.
- Risk of enabling in many places: settings drift, teams lose track of which projects send data, and a later group default can be overridden without anyone noticing.
Keep a list of projects with the integration enabled, along with the owner of each, and review it on a regular schedule.
A staged rollout limits cost and surprises. Start with one representative project, run it through several pipeline types, and check what arrives in Datadog before widening the scope. Move to a subgroup, then a group, and only then consider the instance level.
- Pick a representative pilot: choose a project with typical branches, job types and contributors, so the results reflect your real pipelines.
- Settle billing first: agree with Datadog how many committers count toward CI Visibility before enabling it, since it is priced per committer.
- Decide on optional features: test CI Visibility and job log collection separately so you know what each adds to data volume and cost.
- Set exit criteria: define in writing what must be true before expanding, such as the expected pipeline data appearing in Datadog and a named owner for each project.
Confirm the exact inheritance and override behavior for your installed version in the GitLab Datadog integration documentation before any group or instance change.
Configuring the GitLab Datadog integration in order
This sequence connects a self-managed GitLab instance to Datadog in a controlled way, so the billing question is settled before any optional CI Visibility data flows and a pilot project proves the data before the scope widens.
Confirm the Datadog site and API key
Before touching GitLab, the Datadog administrator confirms which Datadog site your organization uses and issues an API key intended for this integration. Store the key in your secrets manager, not in a shared document. Ask Datadog to confirm how CI Visibility is priced for your account, since it is billed per committer, and record the answer. Done when you have the site, the key stored securely and the billing answer in writing.
Choose the scope level in GitLab
Decide whether the integration is configured at instance, group or project level. Instance settings act as defaults that groups and projects can inherit or override, so a narrow pilot usually starts at project level while the broader rollout is set once higher up. Write down which group or project will be the pilot and who administers the setting. Done when the scope decision and the pilot project are recorded.
Enter the integration settings
An administrator with the required permission opens the Datadog integration in the chosen scope, enters the Datadog site and API key, and saves. Confirm each field name against the current GitLab Datadog integration page, because labels can change between GitLab releases. Leave optional collection options off at this stage. Done when the integration shows as active at the chosen level and the save completes without errors.
Decide on CI Visibility after the billing check
Enable CI Visibility only after the billing answer from Datadog is in hand and approved by the budget owner. Because the integration can optionally turn on CI Visibility, make this a separate, recorded decision rather than a default. Note who approved it and the committer count used for the estimate. Done when the decision is documented, and the setting matches it.
Run a test pipeline in the pilot project
Trigger a pipeline in the pilot project on a non-production branch. The job should run as it normally does, with no changes to the pipeline definition needed for the integration to send data. Note the pipeline ID and branch name so you can find them in Datadog. Done when the pipeline completes in GitLab and the run is recorded for comparison.
Verify the pipeline in Datadog
In Datadog, locate the pipeline from the test run. Confirm it appears, that the expected GitLab project name is recorded, and that the branch and job names match what you saw in GitLab. If CI Visibility is enabled, check that the test-level data you expected is present. If anything is missing or mislabeled, fix the scope or settings and rerun the test before continuing. Done when the record matches the GitLab run.
Widen scope in controlled steps
Once the pilot is verified, extend the integration to further groups or projects, either by setting it at a higher level with inheritance or by enabling it project by project. Review the committer count against the billing answer as more projects send data. Confirm the scope change in Datadog after each step. Done when the agreed scope is live, the record in Datadog matches the scope decision, and the billing check is repeated for the new footprint.
Deciding on CI Visibility and job log collection before enabling them
CI Visibility is optional, so the first decision is whether you need it at all. The GitLab Datadog integration sends pipeline and job information to Datadog without it, and CI Visibility is a separate switch that Datadog prices per committer. Cost therefore follows the number of people committing code in the scope you enable, not the number of pipelines or projects. Before turning it on, count committers across the pilot groups and projects, separate them from people who only read or review, and agree with your team which scope will be billed. Ask Datadog for a quote based on that committer count and on the rollout you plan, and confirm whether the count is taken per month, per year or per billing period.
Job log collection is a data decision rather than a dashboard setting. Job logs are the console output of CI/CD jobs, and they can contain tokens, passwords, connection strings or personal data whenever a script prints a value it should not. Before enabling log collection, review the output of representative jobs in the pilot projects, look for echoed variables and verbose tool flags, and confirm that masked CI/CD variables and protected variables are set where they should be. Fix the scripts first, because masking only hides values that GitLab knows about. Decide which projects may send logs at all, and record who approves that for each group.
Ask Datadog directly for the current CI Visibility pricing, any log retention terms that apply to job logs, the data residency options available to you, and how usage is reported. DeployOpen does not quote Datadog fees, and this page does not state them, so the written quote from Datadog is the figure to plan against. Once the answers are in hand, record them next to your data classification for CI output, so that the security owner, the platform team and the finance contact are deciding from the same facts. If the answers do not fit your rules for retention or location, keep the integration at the instance or group level for pipeline data only and revisit log collection later.
Mapping GitLab pipeline and job data to Datadog views
This table lists each GitLab object the Datadog integration works with, what data it sends, where that data appears in Datadog, and what to check before you rely on it. Use it as a checklist during setup and again after the first pipelines report. The main takeaway is that field names and Datadog views can change, so confirm them against current documentation in your own environment.
| GitLab object | What the integration sends | Where it appears in Datadog | What to verify |
|---|---|---|---|
| Instance settings | Integration defaults set by an administrator, which groups and projects can inherit when enabled at instance level | Not a Datadog view; affects which data reaches Datadog from every project | Confirm which level you configured first and whether lower levels override it |
| Group settings | Pipeline and job information for projects under the group when the integration is enabled at group level | CI Visibility pipeline lists for services tied to those projects | Check that each subgroup inherits or overrides the setting as intended |
| Project settings | Pipeline and job information for a single project, including any project-level override | CI Visibility pipeline and job entries for that project's services | Compare project entries against a test pipeline run to confirm mapping |
| Pipelines | Pipeline status, timing and identifying metadata for each run | Pipeline-level views and filters in CI Visibility | Confirm the current pipeline attribute names in the Datadog and GitLab docs |
| Jobs | Job status, duration, stage and runner-related details for each job | Job-level views, including timing and failure breakdowns | Check which job fields are present in your Datadog plan and version |
| Branches and commit authors | Branch and commit references, plus author information used for committer-based counting | Branch and committer filters, and the per-committer count used for billing | Confirm with Datadog how committers are counted before enabling CI Visibility |
| Job logs (if enabled) | Log output from jobs, sent only when log collection is turned on | Log explorer entries linked to CI jobs | Confirm log collection setting, retention and any cost impact with Datadog first |
Securing the Datadog credentials and job data
The Datadog integration moves pipeline metadata and, if you enable job log collection, job output out of GitLab and into a third-party service. The controls below decide who can change that flow, what secrets can leak into it, and how far it reaches.
Store the API key as a masked, protected variable
Keep the Datadog API key in a GitLab CI/CD variable marked as masked and protected, or pull it at job runtime from an external secrets manager. Masking hides the value in job logs only when it matches the masking rules, so a key containing spaces or line breaks may not mask cleanly. Protected variables are exposed only to pipelines on protected branches and tags. Confirm both settings on the instance, group and project where the integration is configured, and rotate the key if it has ever been set as an unprotected value.
Restrict who can change the integration
The integration settings decide where pipeline data goes, so editing them is a security-relevant change. Limit project maintainer and group owner roles to people who need them, and review who holds those roles on every project that has the integration enabled. Set the integration at group level where possible so that new projects inherit a known configuration rather than each project owner choosing a destination. Record the Datadog site and API key owner in your change records.
Review job scripts for printed secrets
When job log collection is on, anything a job prints can reach Datadog, including values from environment dumps, verbose curl or debug flags, and failed command output. Review the script and before_script sections of pipelines that run with the integration enabled, and remove commands like env or printenv in jobs that hold credentials. Ask your team to confirm that tokens are passed through variables and never echoed into command lines. Treat any secret found in a log as exposed and rotate it.
Narrow the scope of projects sending data
Enabling the integration at group level sends data from every project beneath it, including projects that handle regulated or sensitive code. Where possible, enable it only on the projects whose pipelines you intend to observe, and keep sensitive repositories outside the group that carries the setting. Review the list of enabled projects after each reorganization, because moving or renaming a project can change which settings apply to it. Document the chosen scope so that auditors can compare it with the actual configuration.
Document outbound egress for restricted networks
Datadog delivery is an outbound connection from your GitLab instance or runners to a Datadog endpoint. In air-gapped or tightly filtered networks, this flow is blocked by default and must be an explicit, reviewed exception. Ask Datadog which hostnames and ports your Datadog site requires, then record the source hosts, destination, protocol and data categories in your network documentation. GitLab documents offline operation separately, so confirm with your security team whether this integration is permitted at all in that environment before enabling it.
Why pipeline data does not appear in Datadog
This table lists the failures most often seen when GitLab pipeline data does not reach Datadog, with the likely cause and fix for each. Work down the rows in order, starting with GitLab integration logs and Datadog ingestion status, because those two checks usually show which layer is failing. Confirm each exact setting name and log location in the Datadog integration documentation for your GitLab version.
| Symptom | Likely cause | Fix |
|---|---|---|
| No data at all after saving the integration | First step: check GitLab integration logs and Datadog ingestion status. An invalid or under-scoped Datadog API key, or a key from the wrong Datadog site, rejects the requests. | Generate a key in the correct Datadog organization and site, confirm its scope allows CI data ingestion, then re-save the integration and run a new pipeline. |
| Data appears for some projects but not others | The integration was set at group or project level, or a project overrides the inherited group or instance value. | Compare the integration settings on the affected project with its group and the instance. Remove the local override or set the intended value at the level you want to apply it. |
| Pipelines run but nothing reaches Datadog from runners or GitLab | Outbound egress from GitLab or the runner network is blocked by a firewall, proxy or egress policy for the Datadog endpoint. | Test outbound HTTPS from the GitLab host and from runner hosts to the Datadog endpoint for your site. Add an approved egress rule or proxy configuration, then recheck the integration logs. |
| Expected traces or test data are missing, only pipeline events show | CI Visibility was not enabled, so only the base pipeline and job information is sent. | Enable CI Visibility in the integration settings if you need test and trace data. Confirm with your Datadog account team what CI Visibility includes before enabling it. |
| Datadog invoice rises after enabling CI Visibility | CI Visibility is priced per committer, so enabling it across many committers increases the count billed. | Before enabling, ask Datadog how committers are counted for your organization. Limit CI Visibility to the groups that need it and review the committer count each billing period. |
| Secret values or tokens appear in job logs or Datadog | Job output echoes variables, or logs are collected without masking, so sensitive values are sent with the logs. | Mask and protect CI/CD variables, avoid printing secrets in scripts, and review which job logs are collected before enabling job log collection. Rotate any exposed value. |
| Only some job logs appear in Datadog | Job log collection is off, or logs from jobs that ran before the change were not backfilled. | Enable job log collection if you need logs, then run new pipelines to test. Expect earlier jobs to remain absent unless Datadog confirms a backfill option. |
What teams ask before connecting GitLab to Datadog
How much does the GitLab to Datadog integration cost?
The GitLab integration itself is available in all GitLab tiers, so the cost question is mostly about Datadog. Sending pipeline and job information to Datadog is part of the integration, while the optional CI Visibility feature is priced by Datadog per committer. The charge therefore depends on how many people commit code to the projects you send, not on how many pipelines run. Before you enable anything, ask Datadog for a written quote that states the committer count it will bill, how it counts committers over a billing period, and whether job log collection carries separate charges on your contract. Your own cost is the internal time to configure and verify the integration, plus any partner fees, which follow from a written scope.
How long does a Datadog pilot take compared with a full rollout?
A pilot is usually one group or a small set of projects, and a full rollout covers the instance, several groups and their projects. We do not publish durations for this work, because the time depends on the factors below. A pilot mainly needs one administrator to set the integration at project or group level and one Datadog owner to confirm the data arrives. A full rollout adds decisions about which level to configure, how inheritance and overrides apply, which teams need access to CI Visibility, and how the committer count will be tracked. Ask for a fixed-scope plan that lists the projects, the validation steps and the acceptance criteria before work starts.
What do GitLab administrators and Datadog owners need to provide?
The work needs two sets of people. GitLab administrators decide whether the integration is set at instance, group or project level, and they confirm that the integration allowlist and any group defaults permit it. Datadog owners provide the Datadog site and API key, confirm the account can receive CI data, and agree the CI Visibility billing scope. Security reviewers should approve where the API key is stored and who can read or change it. Ask both teams to name an owner for each decision before the pilot starts, so that the committer count and key rotation have a clear home after handover.
Can an internal team set up the integration without a partner?
Yes, an experienced GitLab administrator can usually configure the integration without outside help, because the setup is documented in the GitLab Datadog integration guide and sits within normal project and group settings. The harder part is agreeing the scope with Datadog, especially the committer count and the data you are willing to send. Teams often need outside help when they want a consistent pattern across many groups, a documented rollback, or evidence that CI data flows as intended. A partner would work from a written scope and deliver the configuration, verification steps and handover notes.
Does the Datadog integration work on air-gapped or restricted networks?
The Datadog integration sends data from GitLab to Datadog's service, so it needs a network path from your GitLab instance to the Datadog endpoint for your region. On an air-gapped network that path does not exist, so the integration cannot send data as configured. Restricted networks may allow the call only through an approved egress proxy or specific destinations. Check the GitLab Datadog integration documentation for the required endpoints and any proxy settings, and confirm with your network team and Datadog which destinations your firewall must allow. Keep in mind that GitLab's offline guidance covers running the instance itself without internet access, which is a separate question.
How do GitLab upgrades affect the Datadog integration?
GitLab ships a minor release monthly and a major release yearly, so the integration will meet version changes over time. Plan each upgrade as a change, and include a check that pipeline and job data still reaches Datadog after the upgrade. GitLab requires upgrades to pass through required upgrade stops, so review the upgrade path before moving versions, and confirm in the Datadog integration documentation whether any setting changes with a release. Keep a short test run in your post-upgrade checklist, using a known pipeline and a Datadog query that confirms the job appears.
What should we verify after the integration is enabled?
Verify three things: that pipeline and job information reaches Datadog for the projects you intended, that no unintended projects send data, and that the CI Visibility scope matches the committer count you agreed. Run a pipeline in a pilot project, find the matching pipeline in Datadog, and check that the job name and status match. Then review the level at which the integration is set, since project settings can override group defaults. Record the result and the Datadog account used, so audit and support teams can trace where the data goes.
How DeployOpen scopes and delivers the GitLab Datadog integration
DeployOpen is a Chainscore Labs company that plans, implements, integrates and supports self-hosted open-source platforms inside your own infrastructure. For GitLab and Datadog CI Visibility, we agree the instance, group and project scope, the data collection choices and the billing questions in writing before any configuration changes are made.
How we scope
- Confirm which GitLab instance, groups and projects will send pipeline and job data to Datadog
- Decide whether the integration is set at instance, group or project level, and where overrides are allowed
- Record whether CI Visibility and job log collection are in or out of scope, with the Datadog per-committer billing confirmed
How we build
- Create the Datadog API key handling and store it in your approved secrets location, not in plain project settings
- Configure the integration at the agreed level and test it against a non-production pipeline first
- Verify that pipeline and job events arrive in Datadog, and that optional CI Visibility data appears only where intended
How we hand over
- Deliver a written record of each configured level, the settings used and the owners of the Datadog account
- Document how to add a new project to the integration and how to remove one cleanly
- Walk your platform and security teams through the verification steps and the billing checks they should repeat
How we support
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts
- Ongoing support, upgrades and continuous testing are available as a retainer
- Ask for a quote based on the written scope, which covers the number of groups, projects and optional data types
