CI/CD Pipeline
Relevant source files
The following files were used as context for generating this wiki page:The docker-docs project utilizes a multi-faceted CI/CD strategy to ensure code quality, documentation integrity, and automated deployment. This includes local validation scripts for contributors, automated workflows on platforms like GitHub Actions and Azure Pipelines for building and testing containerized applications, and a continuous deployment pipeline managed by Netlify for the documentation site itself.
The pipelines described within the documentation serve as guides for end-users to set up their own CI/CD for various application stacks (e.g., Node.js, React). The repository's own CI focuses on validating contributions and deploying the Hugo-based static site. A unique aspect is the use of an internal agent-based system that orchestrates documentation updates and validation.
Sources: CONTRIBUTING.md, content/guides/nodejs/configure-github-actions.md, content/guides/azure-pipelines.md, netlify.toml, agent.yml
Local Validation
Before pushing changes, contributors are encouraged to run local tests to check for issues like broken links and incorrectly formatted markup. This is facilitated by Docker Buildx Bake.
Sources: CONTRIBUTING.md:47-52
Bake Validate Target
The local validation process is defined in the docker-bake.hcl file under the validate target. This command runs a series of checks within a Docker container.
# docker-bake.hcl:1-12
target "validate" {
dockerfile = "Dockerfile.validate"
target = "validate"
tags = ["docker/docs-validator:latest"]
args = {
ALPINE_VERSION = "3.20"
GOLANG_VERSION = "1.22"
HUGO_VERSION = "0.129.0"
NODE_VERSION = "20"
}
}
Sources: docker-bake.hcl:1-12
The validation command is executed via:
$ docker buildx bake validate
This command is also used by the internal documentation agent to run automated checks.
Sources: CONTRIBUTING.md:51, agent.yml:234-236
The following diagram illustrates the local validation flow.
CI Implementations for User Applications
The repository provides detailed guides for setting up CI/CD pipelines for various application types, primarily using GitHub Actions and Azure Pipelines. These serve as reference implementations for users.
GitHub Actions
The recommended GitHub Actions workflow automates building, testing, and pushing Docker images to Docker Hub. The pipeline is typically triggered on push and pull_request events to the main branch.
Sources: content/guides/nodejs/configure-github-actions.md:27-31
Workflow Structure
The workflow is generally structured into one or more jobs. A common pattern involves a test job followed by a build-and-push job, where the second job depends on the successful completion of the first.
This diagram shows a typical two-job workflow for a Node.js application.
Key Steps and Actions
The workflows leverage several official Docker actions and community actions to perform tasks.
| Step | Action Used | Purpose |
|---|---|---|
| Checkout code | actions/checkout@v4 | Checks out the repository source code. |
| Set up Docker Buildx | docker/setup-buildx-action@v3 | Sets up the Docker Buildx builder instance. |
| Cache dependencies | actions/cache@v4 | Caches Docker layers and package manager dependencies (e.g., npm) to speed up runs. |
| Log in to Docker Hub | docker/login-action@v3 | Authenticates with Docker Hub using stored secrets. |
| Build and Push Image | docker/build-push-action@v6 | Builds and pushes the Docker image to a registry. Supports multi-stage builds and multi-platform builds. |
Sources: content/guides/nodejs/configure-github-actions.md:62-145, content/guides/reactjs/configure-github-actions.md:144-210
Secrets and Variables
Secure authentication is handled via GitHub secrets.
| Secret / Variable | Purpose | Example Value |
|---|---|---|
DOCKER_USERNAME | Your Docker Hub username. | your-docker-id |
DOCKERHUB_TOKEN | A Docker Hub Personal Access Token (PAT) with Read/Write permissions. | dckr_pat_... |
DOCKERHUB_PROJECT_NAME | The name of the repository on Docker Hub. | reactjs-sample |
Sources: content/guides/nodejs/configure-github-actions.md:62-73, content/guides/reactjs/configure-github-actions.md:70-81
Azure Pipelines
The documentation also provides a guide for integrating with Azure Pipelines. This involves creating a Service Connection for Docker Hub and defining a pipeline in azure-pipelines.yml.
Sources: content/guides/azure-pipelines.md:16-22
Pipeline Structure
The Azure Pipeline is defined with stages, jobs, and steps. A typical flow involves a single stage BuildAndPush that contains one job to perform all Docker-related actions.
# content/guides/azure-pipelines.md:43-100
stages:
- stage: BuildAndPush
displayName: Build and Push Docker Image
jobs:
- job: DockerJob
displayName: Build and Push
pool:
vmImage: ubuntu-latest
steps:
- checkout: self
- task: Docker@2
displayName: Docker Login
inputs:
command: login
containerRegistry: 'my-docker-registry'
- task: Docker@2
displayName: Build Docker Image
inputs:
command: build
# ...
- task: Docker@2
displayName: Push Docker Image
condition: eq(variables['Build.SourceBranch'], 'refs/heads/main')
inputs:
command: push
# ...
Sources: content/guides/azure-pipelines.md:43-100
The following diagram shows the sequence of tasks in the Azure Pipeline job.
Documentation Site Deployment
The documentation website itself is deployed using Netlify. The configuration is defined in netlify.toml.
Netlify Configuration
The netlify.toml file specifies the build command, the publish directory, and environment variables for the Hugo static site generator.
# netlify.toml:1-10
[build]
command = "hugo --cleanDestinationDir --minify --baseURL $DEPLOY_PRIME_URL"
publish = "public"
[build.environment]
HUGO_VERSION = "0.129.0"
HUGO_ENV = "production"
HUGO_ENABLEGITINFO = "true"
Sources: netlify.toml:1-10
The deployment process is triggered by pushes to the main branch or pull requests, which generate deploy previews.
This diagram outlines the Netlify deployment flow.
Sources: netlify.toml
Summary
The CI/CD ecosystem for the docker-docs project is comprehensive, addressing both internal documentation quality and providing robust, reusable patterns for end-users. Local validation with docker buildx bake empowers contributors to catch errors early. The reference pipelines for GitHub Actions and Azure Pipelines offer best-practice examples for containerized application delivery, emphasizing security, caching, and multi-platform builds. Finally, the Netlify pipeline ensures that the documentation site is continuously and reliably deployed.