Release Process
Relevant source files
The following files were used as context for generating this wiki page:
- hack/releaser/main.go
- hack/releaser/aws.go
- hack/releaser/cloudfront-lambda-redirects.js
- CONTRIBUTING.md
- content/guides/nodejs/configure-github-actions.md
- content/guides/reactjs/configure-github-actions.md
- hack/moby-sync-release.sh
- content/reference/cli/docker/README.md
- agent.yml
- content/contribute/file-conventions.md
The release process for the Docker documentation is a comprehensive workflow that integrates community contributions with automated validation, building, and deployment. It encompasses several key areas: a structured contribution and local testing process, automated CI/CD pipelines using GitHub Actions for building and publishing container images for sample applications, and a sophisticated system for managing and synchronizing content that is vendored from upstream repositories like moby/moby and docker/cli.
This process ensures that documentation is not only accurate and up-to-date but also that related assets, such as sample application images and upstream release notes, are kept in sync with the content. The workflow is designed to handle the complexity of a large documentation site built with Hugo, which includes generated content, vendored modules, and user-contributed guides.
Sources: CONTRIBUTING.md, content/guides/nodejs/configure-github-actions.md, hack/moby-sync-release.sh
Contribution and Pre-Release Validation
The release cycle begins with a contribution. The process is standardized to ensure all changes are validated before being merged.
Sources: CONTRIBUTING.md
Local Development Workflow
Contributors must first set up a local environment to make and test changes. The standard workflow is as follows:
- Fork and Clone: Fork the
docker/docsrepository and clone it locally. - Branching: Create a new branch for the changes.
- Development Server: Use
docker compose watchto start a local development server. This server, available athttp://localhost:1313, watches for file changes and automatically rebuilds the site, enabling rapid iteration. - Local Validation: Before submitting a pull request, contributors must run local tests to check for broken links, incorrect markup, and other issues. This is done with the
docker buildx bake validatecommand.
This local validation step is a critical pre-release check to catch errors early.
Sources: CONTRIBUTING.md:46-79
The following diagram illustrates the local development and validation flow.
Sources: CONTRIBUTING.md:46-79
Automated CI/CD with GitHub Actions
For many guides that include sample applications (e.g., Node.js, React.js), the repository uses GitHub Actions to automate the building, testing, and publishing of Docker images to Docker Hub. This ensures that the code accompanying the documentation is always functional and available.
Sources: content/guides/nodejs/configure-github-actions.md, content/guides/reactjs/configure-github-actions.md
CI/CD Pipeline Overview
The pipeline is typically defined in .github/workflows/main.yml and triggers on push or pull request events to the main branch.
The diagram below shows a typical CI/CD workflow for a sample application.
Key Workflow Steps and Actions
The pipelines leverage several official and community GitHub Actions to perform their tasks.
| Action | Purpose | Source File |
|---|---|---|
actions/checkout@v4 | Checks out the source code in the repository. | content/guides/nodejs/configure-github-actions.md:103-104 |
docker/setup-buildx-action@v3 | Sets up the Docker Buildx builder instance. | content/guides/nodejs/configure-github-actions.md:106-107 |
actions/cache@v4 | Caches dependencies (like npm modules or Docker layers) to speed up subsequent runs. | content/guides/nodejs/configure-github-actions.md:109-114 |
docker/login-action@v3 | Authenticates with a Docker registry, such as Docker Hub, using secrets. | content/guides/nodejs/configure-github-actions.md:158-162 |
docker/build-push-action@v6 | Builds and pushes Docker images. It supports multi-platform builds, caching, and targeting specific stages from a Dockerfile. | content/guides/nodejs/configure-github-actions.md:164-176 |
Testing and Deployment Sequence
The CI pipeline often separates testing from the final build and push. For instance, the Node.js guide's workflow first builds a test image, runs tests against a service container (PostgreSQL), and only proceeds to build the production image if tests pass.
This sequence diagram shows the interaction during the test job.
The final image is often built for multiple architectures (linux/amd64, linux/arm64) and pushed to Docker Hub with both a latest tag and a tag corresponding to the Git commit SHA for traceability.
Sources: content/guides/reactjs/configure-github-actions.md:186-196
Managing Vendored and Generated Content
A significant part of the documentation, particularly reference material, is not written directly in this repository. Instead, it is vendored or generated from upstream sources. This has major implications for the release and update process.
Sources: CONTRIBUTING.md:85-99, agent.yml:32-67, content/reference/cli/docker/README.md
Upstream Content Sources
Several key documentation sections are maintained in their respective product repositories to ensure they are authoritative and synced with the code.
| Content | Upstream Repository |
|---|---|
| CLI Reference | docker/cli |
| Buildx Reference | docker/buildx |
| Compose Reference | docker/compose |
| Dockerfile Reference | moby/buildkit |
| Engine API Reference | moby/moby |
These files are considered read-only within the docker/docs repository. Any required changes must be made in the upstream repository.
Sources: CONTRIBUTING.md:85-99, agent.yml:64-70
CLI Reference Update Process
The CLI reference documentation follows a specific update process:
- Generation: YAML files containing CLI command details are generated from the
docker/clirepository source code. - Transfer: These generated YAML files are then copied into the
_data/engine-clidirectory within thedocker/docsrepository. - Build: During the Hugo site build, stub files in
content/reference/cli/docker/include a partial that parses these YAML files to generate the final HTML pages.
The diagram below outlines this flow.
Synchronizing Moby Release Notes
To ensure consistency between the official documentation and GitHub, a script is used to synchronize the Moby engine release notes.
Sources: hack/moby-sync-release.sh
moby-sync-release.sh Script
This Bash script automates the process of updating the body of a moby/moby GitHub release to match the content from the documentation website.
The script's logic is as follows:
- Accepts a version number (e.g.,
29.0.3) as an argument. - Extracts the relevant release notes section from the markdown files in
content/manuals/engine/release-notes/. - Uses the
ghCLI to fetch the existing release details from themoby/mobyGitHub repository via the API. - If a release for the version does not exist, it prints a
gh release createcommand to create a draft release with the notes. - If the release exists, it compares the notes from the documentation with the body of the GitHub release.
- If they differ, it prints a
gh api patchcommand to update the release body on GitHub.
This flow is visualized below.
Sources: hack/moby-sync-release.sh
Conclusion
The release process for Docker's documentation is a robust and multi-layered system. It effectively balances the need for community contributions with the requirement for technical accuracy and consistency. Key pillars of this process include mandatory local validation for all contributors, powerful CI/CD automation via GitHub Actions for building and publishing related artifacts like sample application images, and a well-defined procedure for synchronizing vendored content from upstream projects. This ensures that the entire documentation ecosystem, from guides to core reference material, remains a reliable and high-quality resource.