@datadog/datadog-ci

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.

README

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
npm install --save-dev @datadog/datadog-ci

# Yarn
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
npx @datadog/datadog-ci [command]

# NPM install globally
npm install -g @datadog/datadog-ci

# Yarn v1 add globally
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

• flare: Troubleshoot your issues with Cloud Run service configuration. 📚

dsyms

• upload: Upload iOS dSYM files for Error Tracking (macOS only). 📚

flutter-symbols

• upload: Upload Flutter symbols for Error Tracking. 📚

unity-symbols

• upload: Upload Unity symbols for Error Tracking.

git-metadata

• upload: Upload Git metadata for the Source Code Integration. 📚

junit

• upload: Upload JUnit test reports for Test Visibility. 📚

lambda

• flare: Troubleshoot your issues with Datadog instrumentation on your AWS Lambda functions.
• instrument: Apply Datadog instrumentation to the given AWS Lambda functions.
• uninstrument: Revert Datadog instrumentation from the given AWS Lambda functions.

measure

• Add measures to a CI Visibility pipeline trace or job span in Datadog. 📚

react-native

• codepush: Upload React Native CodePush sourcemaps for Error Tracking. 📚
• upload: Upload React Native sourcemaps for Error Tracking. 📚
• xcode: Upload React Native sourcemaps for Error Tracking from the XCode bundle build phase. 📚

sarif

• upload: Upload Static Analysis Results Interchange Format (SARIF) reports to Datadog. 📚

sbom

• upload: Upload Software Bill of Materials (SBOM) files to Datadog. 📚

sourcemaps

• upload: Upload JavaScript sourcemaps for Error Tracking. 📚

stepfunctions

• instrument: Instrument AWS Step Function with Datadog to get logs and traces. 📚
• uninstrument: Uninstrument AWS Step Function. 📚

synthetics

• run-tests: Run Continuous Testing tests from the CI. 📚
• upload-application: Upload a new version to an existing mobile application in Datadog. 📚

tag

• Add custom tags to a CI Visibility pipeline trace or job span in Datadog. 📚

trace

• Add custom commands to a CI Visibility pipeline in Datadog. 📚

Beta commands

The following are beta commands, you can enable them with with DD_BETA_COMMANDS_ENABLED=1:

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

• upload: Upload Elf debug info files for Profiling (requires binutils). 📚

gate

• evaluate: Evaluate Quality Gates rules in Datadog. 📚

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 .

Development

Before contributing to this open source project, read our CONTRIBUTING.md.

License

Apache License, v2.0