Overview

Deployments can be performed in your continuous integration (CI) pipelines. Typically, these pipelines have a deployment step that is executed after the source code is tested and the image is built.

If you are executing deployments using a CI provider, you can monitor your deployments with Deployment Visibility. Ensure the following requirements are met:

1. You are using Pipeline Visibility to monitor your CI pipelines.
2. Your CI provider supports the Custom tags and measures at runtime feature, which allows you to add user-defined text and numerical tags to pipelines and jobs in Pipeline Visibility.
3. You are executing deployments in a CI job (or a related level in your CI provider). The concept of a CI job may vary depending on your provider. For more information about how Datadog defines a CI job, see the Terminology section.

Setup

To set up CD Visibility, use the datadog-ci deployment mark command inside the CI job that is performing the deployment.

Two environment variables are required:

1. DD_API_KEY: Point to your Datadog API key.
2. DD_BETA_COMMANDS_ENABLED: Set to 1.

Optionally, you can set DD_SITE environment variable to a specific Datadog site. Your site is .

You can enrich the deployment event that is generated by the datadog-ci deployment mark command using the following parameters:

Use --no-fail (default: false) to prevent the deployment command from failing if there are issues submitting the data.

If you are using GitHub Actions as your CI provider, see the section below for additional considerations.

Once you have added the command to a CI job, the Deployments page and the Deployment Executions Explorer populates with data after pipelines are executed. For more information, see Search and Manage Deployments and the CD Visibility Explorer documentation.

Examples

This set of commands specifies that the CI job executes a deployment to the prod environment with version 1.0.0:

export DD_BETA_COMMANDS_ENABLED=1
export DD_API_KEY="<YOUR_API_KEY>"
export DD_SITE=

datadog-ci deployment mark --env prod --revision 1.0.0

This set of commands specifies that the CI job performs a rollback deployment to the prod environment:

export DD_BETA_COMMANDS_ENABLED=1
export DD_API_KEY="<YOUR_API_KEY>"
export DD_SITE=

datadog-ci deployment mark --env prod --is-rollback

This set of commands specifies that the CI job executes a deployment to the prod environment and adds the team:backend and reason:scheduled tags to the deployment event:

export DD_BETA_COMMANDS_ENABLED=1
export DD_API_KEY="<YOUR_API_KEY>"
export DD_SITE=

datadog-ci deployment mark --env prod --tags team:backend --tags reason:scheduled

Mark GitHub Actions jobs as deployments

To mark GitHub jobs as deployments, datadog-ci CLI version 2.29.0 or higher is required. If the job name does not match the entry defined in the workflow configuration file (the GitHub job ID), the DD_GITHUB_JOB_NAME environment variable needs to be exposed, pointing to the job name. For example:

1. If the job name is changed using the name property:

   jobs:
     deploy:
       name: My deployment job name
       env:
         DD_GITHUB_JOB_NAME: My deployment job name
       steps:
       - run: datadog-ci deployment mark ...
   

2. If the matrix strategy is used, several job names are generated by GitHub by adding the matrix values at the end of the job name, within parenthesis. The DD_GITHUB_JOB_NAME environment variable should then be conditional on the matrix values:

   jobs:
     deployment:
       strategy:
         matrix:
           env: [dev, staging]
       env:
         DD_GITHUB_JOB_NAME: deployment (${{ matrix.env }})
       steps:
       - run: datadog-ci deployment mark ...
   

Further reading

Additional helpful documentation, links, and articles:

Learn about Deployment VisibilityDOCUMENTATION Learn how to query and visualize deployment executionsDOCUMENTATION