Documentation deployments

Deployment environments

The GitLab documentation site is a static site hosted by GitLab Pages. The deployment is done by the Pages deploy job.

The website hosts documentation only for the currently supported GitLab versions. Documentation for older versions is built and uploaded as Docker images to be downloaded from GitLab Docs archives.

Parts of release process

The documentation release process involves:

  • Merge requests, to make changes to the main and relevant stable branches.
  • Pipelines, to build and deploy Docker images to the gitlab-docs container 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

Pipelines for stable branches in the documentation project pull the relevant stable branches of included projects. For example, the documentation for stable version 14.4 is built from the 14.4 branch of the gitlab-docs project, which then includes:

  • The 14-4-stable-ee branch of the gitlab project.
  • The 14-4-stable branch of the gitlab-runner project.
  • The 14-4-stable branch of the omnibus-gitlab project.
  • The 5-4-stable branch of the charts/gitlab project. charts/gitlab versions are mapped to GitLab versions.

The Technical Writing team creates the stable branch for the gitlab-docs project, which makes use of the stable branches created by other teams.

Stable documentation

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:

In particular, the image:docs-single job in each pipeline runs automatically. It takes what is built, and pushes it to the container registry.

graph TD A["14.4 MR merged"] B["14.3 MR merged"] C["14.2 MR merged"] D["13.12 MR merged"] E["12.10 MR merged"] F{{"Container registry on gitlab-docs project"}} A--"image:docs-single<br>job runs and pushes<br>gitlab-docs:14.4 image"-->F B--"image:docs-single<br>job runs and pushes<br>gitlab-docs:14.3 image"-->F C--"image:docs-single<br>job runs and pushes<br>gitlab-docs:14.2 image"-->F D--"image:docs-single<br>job runs and pushes<br>gitlab-docs:13.12 image"-->F E--"image:docs-single<br>job runs and pushes<br>gitlab-docs:12.10 image"-->F

Rebuild stable documentation images

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, rebuild the 14.4 Docker image to include changes subsequently merged in the gitlab project’s 14-4-stable-ee branch.
  • To incorporate changes made to the gitlab-docs project itself to a stable branch. For example:

Latest documentation

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.

The image:docs-latest job:

  • Pulls the latest documentation from the default branches of the relevant upstream projects.
  • Pulls the Docker images previously built by the image:docs-single jobs.
  • Must be run manually on a scheduled pipeline.

For example, a pipeline containing the image:docs-latest job:

graph TD A["Latest gitlab, gitlab-runner<br>omnibus-gitlab, and charts"] subgraph "Container registry on gitlab-docs project" B["14.4 versioned docs<br>gitlab-docs:14.4"] C["14.3 versioned docs<br>gitlab-docs:14.3"] D["14.2 versioned docs<br>gitlab-docs:14.2"] E["13.12 versioned docs<br>gitlab-docs:13.12"] F["12.10 versioned docs<br>gitlab-docs:12.10"] end G[["Scheduled pipeline<br>image:docs-latest job<br>combines all these"]] A--"Default branches<br>pulled down"-->G B--"gitlab-docs:14.4 image<br>pulled down"-->G C--"gitlab-docs:14.3 image<br>pulled down"-->G D--"gitlab-docs:14.2 image<br>pulled down"-->G E--"gitlab-docs:13.12 image<br>pulled down"-->G F--"gitlab-docs:12.10 image<br>pulled down"-->G H{{"Container registry on gitlab-docs project"}} G--"Latest gitlab-docs:latest image<br>pushed up"-->H

Pages deploy job

GitLab Docs is a Pages site and documentation updates for it must be deployed to become available.

The pages job runs automatically when a pipeline runs on the default branch (main). It runs the necessary commands to combine:

  • A very up-to-date build of the gitlab-docs site code.
  • The latest docs from the default branches of the upstream projects.
  • The documentation from image:docs-latest.

For example, a pipeline containing the pages job.

graph LR A{{"Container registry on gitlab-docs project"}} B[["Scheduled pipeline<br>`pages` and<br>`pages:deploy` job"]] C([docs.gitlab.com]) A--"gitlab-docs:latest<br>pulled"-->B B--"Unpacked documentation uploaded"-->C

Manually deploy to production

GitLab Docs is deployed to production whenever the Build docs.gitlab.com every hour scheduled pipeline runs. By default, this pipeline runs every hour.

Maintainers can manually run this pipeline to force a deployment to production:

  1. Go to the scheduled pipelines for gitlab-docs.
  2. Next to Build docs.gitlab.com every hour, select Play ().

The updated documentation is available in production after the pages and pages:deploy jobs complete in the new pipeline.

If you do not have the Maintainer role to perform this task, ask for help in the #docs Slack channel.

Docker files

The dockerfiles directory contains Dockerfiles needed to build, test, and deploy https://docs.gitlab.com.

Troubleshooting

Not a known icon in @gitlab-org/gitlab-svg

If you attempt to use an icon in the UI or documentation and receive this error in the docs-lint links job, the html-lint Docker image needs an update: 

ArgumentError: example-image is not a known icon in @gitlab-org/gitlab-svg
926lib/helpers/icons_helper.rb:22:in `icon':
example-image is not a known icon in @gitlab-org/gitlab-svg (ArgumentError)

Use the #docs channel in Slack to request a member of the Technical Writing team update the Docker image. For more information, see the internal Technical Writing team documentation.