CI/CD and Preview Builds
Relevant source files
The following files were used as context for generating this wiki page:The Datadog documentation project utilizes a robust CI/CD pipeline to manage contributions, ensure quality, and automate deployments to the live documentation site. The system is built around GitHub, Hugo (a static site generator), and a GitLab pipeline for CI processes. A key feature of this workflow is the generation of preview builds for pull requests, which allows contributors and reviewers to see changes in a staging-like environment before they are merged into the main branch.
This process is critical for maintaining the quality of the documentation. It relies on specific contribution guidelines, particularly branch naming conventions for Datadog employees, to trigger the automated preview builds. Merging a pull request to the master branch automatically initiates a deployment to the production documentation site.
Sources: README.md:3-20, CLAUDE.md:5-7, CONTRIBUTING.md:7-9
Contribution and Build Workflow
The CI/CD process starts when a contributor, whether internal or external, creates a pull request. The workflow varies slightly based on whether the contributor is a Datadog employee.
Sources: README.md:22-49
Contributor Process Flow
The following diagram illustrates the general workflow for all contributors.
This diagram shows the contribution paths for both external and internal contributors, highlighting the critical branch naming step for internal staff that enables preview builds.
Sources: README.md:22-49, CONTRIBUTING.md:7-9
Branch Naming and Preview Builds
For Datadog employees, a specific branch naming convention is mandatory to trigger the CI pipeline and generate a preview build. External contributors do not need to follow this convention.
Convention: The branch name MUST follow the format <name>/<description>. The presence of the forward slash (/) is critical.
Consequences of non-compliance:
- The GitLab pipeline will not run.
- No branch preview will be generated.
- The pull request will not pass CI checks.
When a branch is named correctly, a GitHub bot automatically posts a link to a preview website for the pull request after the preview build is complete. This allows for easy review of all changes.
Sources: README.md:36-49, CLAUDE.md:46-50, CONTRIBUTING.md:7-9
The logic for triggering a preview build is visualized below.
This diagram illustrates how the branch naming convention directly impacts the CI pipeline and the generation of a preview build.
Sources: README.md:36-49, CLAUDE.md:46-50
Build System and Environments
The documentation site's build process is orchestrated by a Makefile and leverages a combination of tools to generate the static site. The system operates in distinct environments for development, previewing, and production.
Sources: CLAUDE.md:10-44
Core Technologies
| Tool | Purpose |
|---|---|
| Hugo | The primary static site generator. |
| Node.js | Used for package management (Yarn), build automation, and asset processing (SCSS, JavaScript). |
| Python | Used for content processing, fetching integration data, and managing translations. |
| Makefile | Orchestrates the entire build process, managing dependencies and running various build commands. |
| Goldmark | The Markdown renderer, compliant with CommonMark. |
Sources: README.md:53-55, CLAUDE.md:28-35
Build Environments
The project uses three main build environments, each with a specific purpose and configuration.
| Environment | Purpose | Trigger |
|---|---|---|
| Development | For local development with drafts and hot-reloading. | yarn start or make start |
| Preview | Generates branch previews for Pull Requests. | PR from a correctly named branch. |
| Live | The production deployment on docs.datadoghq.com. | Merge to master branch. |
Sources: CLAUDE.md:71-75
Key Build Commands
Several commands are available to manage dependencies and build the site.
| Command | Description |
|---|---|
yarn start / make start | Full build including external dependencies and runs the development server. |
yarn build / make build | Creates a production build. |
yarn run build:preview | Builds the site with the preview environment configuration. |
make dependencies | Installs all dependencies (Node, Python, external repos). |
Sources: CLAUDE.md:11-22
Deployment Pipeline
The deployment process is fully automated upon merging changes into the master branch.
This sequence diagram shows the automated deployment process triggered by a merge to the master branch.
Sources: README.md:57-58
CI/CD Integrations and Monitoring
The CI/CD pipeline itself is a candidate for monitoring and testing using Datadog's own products, such as CI Visibility and Continuous Testing.
Sources: content/fr/continuous_testing/cicd_integrations/github_actions.md, content/en/continuous_integration/search/_index.md
Running Continuous Tests in CI
Workflows can be configured to run Datadog Synthetic tests directly from a CI provider like GitHub Actions. This ensures that end-to-end user flows remain functional.
The following is an example of a GitHub Actions workflow that runs Synthetic tests using DataDog/synthetics-ci-github-action.
name: Exécuter des tests Synthetic avec des ID de test publics
jobs:
e2e_testing:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Run Datadog Synthetic tests
uses: DataDog/synthetics-ci-github-action@v0.17.0
with:
api_key: ${{secrets.DD_API_KEY}}
app_key: ${{secrets.DD_APP_KEY}}
public_ids: 'abc-d3f-ghi, jkl-mn0-pqr'
Sources: content/fr/continuous_testing/cicd_integrations/github_actions.md:18-30
CI Visibility
Datadog's CI Visibility provides insights into the performance and reliability of the build pipelines. The Pipelines page offers an overview of the entire build system, with aggregated stats for pipeline runs. This allows the team to monitor:
- Build frequency and failure rates.
- Median duration of pipelines and jobs.
- Performance regressions introduced by commits.
- The critical path of jobs to identify bottlenecks.
Sources: content/en/continuous_integration/search/_index.md:11-25, 62-67