- Stable branches
- Stable documentation
- Latest documentation
- Documentation Pages deployment
- Docker files
The documentation release process involves:
- Merge requests, to make changes to the
mainand relevant stable branches.
- Pipelines, to build and deploy Docker images to the
gitlab-docscontainer registry for the relevant stable branches.
- Docker images used to build and deploy all the online documentation, including stable versions and the latest documentation.
Documentation deployments have dependencies on pipelines and Docker images as follows:
- The latest documentation pipelines and images depend on the stable documentation pipelines and images.
- The Pages deployment pipelines depend on the latest documentation images (which, in turn, depend on the stable pipelines and images.)
For general information on using Docker with CI/CD pipelines, see Docker integration.
Stable branches for documentation include the relevant stable branches of all the projects required to publish the entire
documentation suite. For example, the stable version of documentation for version
14.4branch of the
14-4-stable-eebranch of the
14-4-stablebranch of the
14-4-stablebranch of the
5-4-stablebranch of the
charts/gitlabversions are mapped to GitLab versions.
The Technical Writing team
creates the stable branch
gitlab-docs project, which makes use of the stable branches created by other teams.
When merge requests are merged that target stable branches of
gitlab-docs, a pipeline builds
that stable documentation and deploys it to the registry. For example:
- 14.4 merge request pipeline.
- 14.3 merge request pipeline.
- 14.2 merge request pipeline.
- 13.12 merge request pipeline.
- 12.10 merge request pipeline.
To rebuild any of the stable documentation images, create a new pipeline for the stable branch of the image to rebuild. You might do this:
- To include new documentation changes from an upstream stable branch into a stable version Docker image. For example,
14.4Docker image to include changes subsequently merged in the
- To incorporate changes made to the
gitlab-docsproject itself to a stable branch. For example:
- CSS style changes.
- Changes to the version menu for a new release.
We build a Docker image (tagged
latest) that contains:
- The latest online version of the documentation.
- The documentation from the stable branches of upstream projects.
- Pulls the latest documentation from the default branches of the relevant upstream projects.
- Pulls the Docker images previously built by the
- Must be run manually on a scheduled pipeline.
job runs automatically when a pipeline runs on the default branch (
It runs the necessary commands to combine:
- A very up-to-date build of the
- The latest docs from the default branches of the upstream projects.
- The documentation from
|Contains all the dependencies that are needed to build the website. If the gems are updated and |
|Base image to build the docs website. It uses |
|Base image to use for building documentation archives. It uses |
|Contains all the versions of the website in one archive. It copies all generated HTML files from every version in one location.|
Although build images are built automatically via GitLab CI/CD, you can build and tag all tooling images locally:
- Make sure you have Docker installed.
- Make sure you’re in the
dockerfiles/directory of the
Build the images:
docker build -t registry.gitlab.com/gitlab-org/gitlab-docs:bootstrap -f Dockerfile.bootstrap ../ docker build -t registry.gitlab.com/gitlab-org/gitlab-docs:builder-onbuild -f Dockerfile.builder.onbuild ../ docker build -t registry.gitlab.com/gitlab-org/gitlab-docs:nginx-onbuild -f Dockerfile.nginx.onbuild ../
For each image, there’s a manual job under the
images stage in
.gitlab-ci.yml which can be invoked at any time.