Deployment to Production
Relevant source files
The following files were used as context for generating this wiki page:
The Datadog documentation site is a static website generated using Hugo. The deployment to the production environment, docs.datadoghq.com, is an automated process triggered by contributions to the master branch of the repository. This page outlines the complete workflow, from creating a contribution to the final release.
The core principle of the deployment process is that merging a pull request into the master branch initiates an automatic deployment. This process typically starts within 10 minutes of the merge and takes around 35 minutes to complete, although times can vary.
Sources: README.md:5-6, README.md:52-54
Contribution and Pre-Deployment Workflow
Before any code reaches production, it must go through a specific contribution and review process that leverages a CI/CD pipeline. The process differs slightly for internal Datadog staff and external contributors.
Sources: README.md:19-40, CONTRIBUTING.md:7
Branching Strategy
A strict branching strategy is enforced, especially for Datadog employees, as it is critical for the CI pipeline to function correctly.
| Contributor Type | Branching Instructions |
|---|---|
| Datadog Staff | Must create branches off master with the name format <name>/<description>. The forward slash (/) is mandatory for the GitLab pipeline to run, generate a branch preview, and pass CI checks. |
| Outside Contrib | Must fork the master branch, make changes in their fork, and then open a pull request back to the DataDog/master branch. |
Failure for internal staff to follow the naming convention results in the CI pipeline not running and no preview link being generated for the pull request.
Sources: README.md:22-31, CLAUDE.md:54-57
Pull Request and CI Pipeline
Once changes are ready, the contributor creates a pull request (PR) against the master branch. This action triggers a series of automated checks and builds.
The following diagram illustrates the pre-deployment workflow:
This diagram shows the contribution flow, highlighting the importance of branch naming for CI pipeline success and the process leading to a PR merge.
Sources: README.md:32-40, CLAUDE.md:54-57
Automated Deployment Process
Merging a pull request to the master branch is the sole trigger for an automatic deployment to the production documentation site.
Deployment Sequence
The sequence of events from a developer's merge action to the live deployment is as follows:
This diagram shows the automated sequence triggered by a merge to the master branch, culminating in the new documentation version being live.
Sources: README.md:52-54, CLAUDE.md:21
Monitoring Deployments
While the documentation repository itself has a simple deployment trigger, the content within it describes how to monitor more complex deployment processes using Datadog's CD Visibility product. This involves marking a CI job as a deployment to send deployment events to Datadog.
Sources: content/en/continuous_delivery/deployments/ciproviders.md:14-19
Marking a CI Job as a Deployment
To monitor a deployment performed within a CI pipeline, the datadog-ci deployment mark command is used inside the relevant CI job. This command requires DD_API_KEY and DD_BETA_COMMANDS_ENABLED environment variables to be set.
Sources: content/en/continuous_delivery/deployments/ciproviders.md:35-40
The command can be enriched with several parameters to provide context about the deployment:
| Parameter | Description | Required |
|---|---|---|
--env | The environment of the deployment (e.g., prod). | Yes |
--service | The name of the service being deployed. | Yes |
--revision | The version or revision being deployed (e.g., a git hash or version number). | No |
--is-rollback | A flag to specify if the deployment is a rollback. | No |
--tags | Custom key-value tags to add to the deployment event. | No |
Sources: content/en/continuous_delivery/deployments/ciproviders.md:47-54
An example of using the command in a CI job:
export DD_BETA_COMMANDS_ENABLED=1
export DD_API_KEY="<YOUR_API_KEY>"
export DD_SITE="datadoghq.com"
datadog-ci deployment mark --env prod --service transaction-service --revision 1.0.0
Sources: content/en/continuous_delivery/deployments/ciproviders.md:61-66
Visualizing Deployments
Once deployment data is sent to Datadog, it can be visualized on the Deployments and Deployment Executions pages. These pages provide aggregated stats like failure rate, median duration, and the status of the latest deployment for each service and environment. This allows teams to identify which deployments are failing or taking the most time.
The relationship between the CI job and the visualized deployment is shown below:
This diagram shows how the datadog-ci command links a CI job to a visible deployment event in the Datadog platform.
Sources: content/en/continuous_delivery/explorer/_index.md:16-22, content/en/continuous_delivery/deployments/ciproviders.md:68-71
Maintaining the Production Environment
After a successful deployment, ongoing maintenance is required to ensure the health of the production system. The documentation describes this as the "run" phase for Datadog administrators. Key activities include:
- Usage Monitoring: Keeping track of consumption using estimated usage metrics and dashboards.
- Agent Updates: Regularly updating Datadog Agent components for security and feature enhancements. It is recommended to subscribe to the release feed and use Fleet Automation to manage upgrades.
- API Key Rotation: Following standard security practices for API and App keys, including periodic rotation.
- RBAC Management: Collaborating with SAML/AD admins to manage user roles and permissions.
These tasks are crucial for the long-term stability and security of the production environment.
Sources: content/en/administrators_guide/run.md:7-9, content/en/administrators_guide/run.md:43-69
Summary
Deployment to production for the Datadog documentation site is a streamlined, automated process centered around merging pull requests to the master branch. The integrity of this process relies on a strict branching strategy that enables the CI/CD pipeline to build, test, and generate previews. While the deployment trigger is simple, the repository's content provides extensive guidance on how to monitor and manage complex deployment workflows and maintain a healthy production environment using Datadog's own suite of tools.
Sources: README.md:52-54, content/en/administrators_guide/run.md:71-74