What is @datadog/datadog-ci?
@datadog/datadog-ci is an npm package that provides a set of tools to interact with Datadog from your CI/CD pipelines. It allows you to upload test results, monitor performance, and manage various Datadog resources programmatically.
What are @datadog/datadog-ci's main functionalities?
Upload JUnit XML Test Reports
This feature allows you to upload JUnit XML test reports to Datadog. It helps in tracking test results and visualizing them in Datadog dashboards.
const { uploadJUnitXML } = require('@datadog/datadog-ci');
uploadJUnitXML({
service: 'my-service',
files: ['test-results.xml'],
tags: ['env:ci', 'team:backend'],
datadogSite: 'datadoghq.com',
apiKey: 'your-datadog-api-key'
}).then(() => {
console.log('Test results uploaded successfully');
}).catch((error) => {
console.error('Error uploading test results:', error);
});
Synthetics Command
This feature allows you to run Datadog Synthetics tests from your CI/CD pipeline. It helps in monitoring the performance and availability of your applications.
const { synthetics } = require('@datadog/datadog-ci');
synthetics.runTests({
publicIds: ['abc-123', 'def-456'],
datadogSite: 'datadoghq.com',
apiKey: 'your-datadog-api-key',
appKey: 'your-datadog-app-key'
}).then((results) => {
console.log('Synthetics tests results:', results);
}).catch((error) => {
console.error('Error running synthetics tests:', error);
});
API Test
This feature allows you to run API tests defined in a configuration file. It helps in ensuring the reliability and correctness of your APIs.
const { apiTest } = require('@datadog/datadog-ci');
apiTest.run({
configPath: './api-test-config.json',
datadogSite: 'datadoghq.com',
apiKey: 'your-datadog-api-key',
appKey: 'your-datadog-app-key'
}).then((results) => {
console.log('API test results:', results);
}).catch((error) => {
console.error('Error running API tests:', error);
});
Other packages similar to @datadog/datadog-ci
jest-junit
jest-junit is a Jest reporter that creates compatible JUnit XML files. It is similar to the JUnit XML upload feature of @datadog/datadog-ci but is specific to Jest test results.
newman
Newman is a command-line collection runner for Postman. It allows you to run and test Postman collections directly from the command line. It is similar to the API test feature of @datadog/datadog-ci but is specific to Postman collections.
cypress
Cypress is a JavaScript end-to-end testing framework. It provides a rich set of features for writing and running tests for web applications. It is similar to the Synthetics command feature of @datadog/datadog-ci but is a more comprehensive testing framework.
Datadog CI

Execute commands from your Continuous Integration (CI) and Continuous Delivery (CD) pipelines to integrate with existing Datadog products.
See the Usage section for a list of available commands.
How to install the CLI
The package is under @datadog/datadog-ci and can be installed through NPM or Yarn:
npm install --save-dev @datadog/datadog-ci
yarn add --dev @datadog/datadog-ci
If you need datadog-ci
as a CLI tool instead of a package, you can run it with npx
or install it globally:
npx @datadog/datadog-ci [command]
npm install -g @datadog/datadog-ci
yarn global add @datadog/datadog-ci
For more ways to install the CLI, see this section.
Usage
Usage: datadog-ci <command> [<subcommand>] [options]
The following values are available for each <command>
and (optionally) <subcommand>
.
See each command's linked README for more details, or click on 📚 to see the related documentation page.
cloud-run
dsyms
flutter-symbols
unity-symbols
git-metadata
junit
lambda
measure
- Add measures to a CI Visibility pipeline trace or job span in Datadog. 📚
react-native
sarif
sbom
sourcemaps
stepfunctions
synthetics
tag
- Add custom tags to a CI Visibility pipeline trace or job span in Datadog. 📚
trace
Beta commands
The following are beta commands, you can enable them with with DD_BETA_COMMANDS_ENABLED=1
:
coverage
upload
: Upload code coverage report files to Datadog. (📚: no public documentation page yet)
deployment
mark
: Mark a CI job as a deployment. 📚
correlate
: Correlate GitOps CD deployments with application repositories CI pipelines. 📚
dora
deployment
: Send a new deployment event for DORA Metrics to Datadog. 📚
elf-symbols
pe-symbols
gate
FIPS support
The fips
option allows datadog-ci
to use a FIPS cryptographic module provider if the OpenSSL library installed on the host system provides it.
Note: datadog-ci
cannot assert if such a provider is available, and doesn't throw any error if the provider is not FIPS validated.
Node.js versions below 17 are incompatible with OpenSSL 3, which provides FIPS support.
If you are using a Node.js version below 17, enabling the fips
option causes the command to throw an error.
The option fips-ignore-error
ignores this error.
The released datadog-ci
binary now uses Node.js version 18 to be compatible with OpenSSL 3.
fips
Enable datadog-ci
FIPS support if a FIPS validated provider is installed on the host system.
If you do not have a FIPS provider installed, datadog-ci
does not raise an error.
ENV variable: DATADOG_FIPS=true
CLI param: --fips
fips-ignore-error
Ignore Node.js errors if FIPS cannot be enabled on the host system.
Note: the absence of an error doesn't indicate that FIPS is enabled successfully.
ENV variable: DATADOG_FIPS_IGNORE_ERROR=true
CLI param: --fips-ignore-error
More ways to install the CLI
Standalone binary
If installing NodeJS in the CI is an issue, standalone binaries are provided with releases. linux-x64, linux-arm64, darwin-x64, darwin-arm64 (MacOS) and win-x64 (Windows) are supported.
To install:
Linux
curl -L --fail "https://github.com/DataDog/datadog-ci/releases/latest/download/datadog-ci_linux-x64" --output "/usr/local/bin/datadog-ci" && chmod +x /usr/local/bin/datadog-ci
MacOS
curl -L --fail "https://github.com/DataDog/datadog-ci/releases/latest/download/datadog-ci_darwin-x64" --output "/usr/local/bin/datadog-ci" && chmod +x /usr/local/bin/datadog-ci
Windows
Invoke-WebRequest -Uri "https://github.com/DataDog/datadog-ci/releases/latest/download/datadog-ci_win-x64" -OutFile "datadog-ci.exe"
Then, you can run datadog-ci
commands normally:
datadog-ci version
Container image
To run datadog-ci
from a container, you can use the datadog/ci
image available in Docker Hub as well as the public Amazon ECR and Google GC registries.
docker pull datadog/ci
This example demonstrates how to run a command using the container and passing in the API and app keys:
export DD_API_KEY=$(cat /secret/dd_api_key)
export DD_APP_KEY=$(cat /secret/dd_app_key)
docker run --rm -it -v $(pwd):/w -e DD_API_KEY -e DD_APP_KEY datadog/ci synthetics run-tests -p pub-lic-id1
Building your own container image
You can build an image using the provided Dockerfile:
cd container
docker build --tag datadog-ci .
Optionally, you can use the VERSION
build argument to build an image for a specific version:
docker build --build-arg "VERSION=v1.14" --t datadog-ci .
Migration guide
If you are upgrading from a previous major version, read our MIGRATING.md document to understand the changes and how to adapt your scripts.
Development
Before contributing to this open source project, read our CONTRIBUTING.md document.
License
Apache License, v2.0