plugin-dora

DORA Metrics

Send deployment events for DORA Metrics from CI.

Usage

Commands

deployment

This command sends details to Datadog about a deployment of a service.

$ datadog-ci dora deployment [--service #0] [--env #0] [--dry-run]

━━━ Options ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  --started-at #0            In Unix seconds or ISO8601. (Examples: 1699960648, 2023-11-14T11:17:28Z)
  --finished-at #0           In Unix seconds or ISO8601. (Examples: 1699961048, 2023-11-14T11:24:08Z)
  --git-repository-url #0    Example: https://github.com/DataDog/datadog-ci.git
  --git-commit-sha #0        Example: 102836a25f5477e571c73d489b3f0f183687068e
  --version #0               Example: 1.0.0
  --team #0                  Example: my-team
  --custom-tags #0           Example: department:engineering
  --skip-git                 Disables sending git URL and SHA. Change Lead Time will not be available

For example:

datadog-ci dora deployment --service my-service --env prod \
    --started-at 1699960648 --finished-at 1699961048 \
    --git-repository-url https://github.com/my-organization/my-repository \
    --git-commit-sha 102836a25f5477e571c73d489b3f0f183687068e

--service (or DD_SERVICE) and --started-at are always required and --git-repository-url and --git-commit-sha are necessary for Change Lead Time.

• --service (default: DD_SERVICE env var) should be set as the name of the service that was deployed.
• --env (default: DD_ENV env var) is a string that represents the environment that was targeted by the deployment.
• --started-at (required) is the timestamp in Unix seconds or ISO8601 when the deployment started.
• --finished-at (default: current timestamp) is the timestamp in Unix seconds or ISO8601 when the deployment finished.
• --git-repository-url is a string with the repository URL for the deployed service. If this is missing, the URL is retrieved from the local git repository.
• --git-commit-sha is a string with the git commit SHA that has been deployed. If this is missing, the current HEAD is retrieved from the local git repository.
• --version is a string of the version associated with the deployment.
• --team is a string of the team associated with the deployment. If this is missing, the team associated with the service in the Software Catalog will be used.
• --custom-tags is an array of strings of custom tags to add to the deployment event in the form key:value. A max of 100 tags can be added to each deployment.
• --skip-git (default: false): Disables sending git URL and SHA. Change Lead Time will not be available
• --dry-run (default: false): It runs the command without actually sending the event. All other checks are still performed.

Environment variables

Additionally, you can configure the deployment command with environment variables:

• DD_API_KEY (required): API key used to authenticate the requests.
• DD_ENV: you may choose the environment you that the deployment has targetted
• DD_SERVICE: If you haven't specified a service through --service you can set it with this env var.
• DD_SITE: Set to your Datadog site. For example, datadoghq.com or datadoghq.eu.

Optional dependencies

• git is used for extracting repository URL and commit SHA automatically.

End-to-end testing process

To verify this command works as expected, you can use --dry-run:

export DD_API_KEY='<API key>'

yarn launch dora deployment --service test-service --started-at `date +%s` --dry-run

This is an example of a successful output:

⚠️ --git-repository-url or --git-commit-sha not provided.
Assuming deployment of the current HEAD commit: git@github.com:DataDog/datadog-ci.git 400beb0f276d923846cf778b9dbe9cf101306e41
This warning can be disabled with --skip-git but git data is required for Change Lead Time.
[DRYRUN] Sending DORA deployment event for service: dora-api
 data: {
  "service": "dora-api",
  "startedAt": "2023-11-14T17:14:16.000Z",
  "finishedAt": "2023-11-14T17:14:18.574Z",
  "git": {
    "repoURL": "git@github.com:DataDog/datadog-ci.git",
    "commitSHA": "400beb0f276d923846cf778b9dbe9cf101306e41"
  }
}

Further reading

Additional helpful documentation, links, and articles:

• Learn about DORA Metrics