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 [scope]

# 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.

Installing a plugin

Plugins are separate packages that were split from the @datadog/datadog-ci package to reduce its installation size.

Use datadog-ci plugin list to list the available plugins:

datadog-ci plugin list

Use datadog-ci plugin install to install a plugin:

datadog-ci plugin install <scope>

By default, running a command that requires a plugin will automatically install the plugin if it is not already installed. You can disable this behavior with DISABLE_PLUGIN_AUTO_INSTALL=1.

Usage

Usage: datadog-ci <scope> <command> [options]

The following <scope> and <command> values are available.

aas

_{README: 📚 | Documentation: 🔗 | Plugin: @datadog/datadog-ci-plugin-aas}

• instrument: Apply Datadog instrumentation to the given Azure App Services.
• uninstrument: Revert Datadog instrumentation from the given Azure App Services.

cloud-run

_{README: 📚 | Documentation: 🔗 | Plugin: @datadog/datadog-ci-plugin-cloud-run}

• flare: Troubleshoot your issues with Cloud Run service configuration.
• instrument: Apply Datadog instrumentation to the given Cloud Run Services.
• uninstrument: Revert Datadog instrumentation from the given Cloud Run Services.

coverage

_{README: 📚 | Documentation: 🔗}

• upload: Upload code coverage report files to Datadog.

dora

_{README: 📚 | Documentation: 🔗}

• deployment: Send a new deployment event for DORA Metrics to Datadog.

dsyms

_{README: 📚 | Documentation: 🔗}

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

flutter-symbols

_{README: 📚 | Documentation: 🔗}

• upload: Upload Flutter symbols for Error Tracking.

gate

_{README: 📚 | Documentation: 🔗}

• evaluate: Evaluate Quality Gates rules in Datadog.

git-metadata

_{README: 📚 | Documentation: 🔗}

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

junit

_{README: 📚 | Documentation: 🔗}

• upload: Upload JUnit test reports for Test Visibility.

lambda

_{README: 📚 | Documentation: 🔗 | Plugin: @datadog/datadog-ci-plugin-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

_{README: 📚 | Documentation: 🔗}

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

pe-symbols

_{README: 📚 | Documentation: 🔗}

• upload: Upload Windows PE debug info files for Profiling.

react-native

_{README: 📚 | Documentation: 🔗}

• 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

_{README: 📚 | Documentation: 🔗}

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

sbom

_{README: 📚 | Documentation: 🔗}

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

sourcemaps

_{README: 📚 | Documentation: 🔗}

• upload: Upload JavaScript sourcemaps for Error Tracking.

stepfunctions

_{README: 📚 | Documentation: 🔗 | Plugin: @datadog/datadog-ci-plugin-stepfunctions}

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

synthetics

_{README: 📚 | Plugin: @datadog/datadog-ci-plugin-synthetics}

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

tag

_{README: 📚 | Documentation: 🔗}

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

trace

_{README: 📚 | Documentation: 🔗}

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

unity-symbols

_{README: 📚 | Documentation: 🔗}

• upload: Upload Unity symbols for Error Tracking.

Beta commands

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

deployment

_{README: 📚 | Documentation: 🔗}

• mark: Mark a CI job as a deployment.
• correlate: Correlate GitOps CD deployments with application repositories CI pipelines. 🔗
• correlate-image: Correlate an image from a CD provider with its source commit. 🔗
• gate: Evaluate a Deployment Gate. 🔗

elf-symbols

_{README: 📚 | Documentation: 🔗}

• upload: Upload Elf debug info files for Profiling.

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 <command> [<subcommand>] [options]

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=v3.9.0" --tag 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