gitlab-org--gitlab-foss/doc/development/documentation/site_architecture/deployment_process.md

stage	group	info
none	unassigned	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments

Documentation deployments

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

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.4 includes:

• The 14.4 branch of the gitlab-docs project.
• 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:

• 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.

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:
  • CSS style changes.
  • Changes to the version menu for a new release.

Latest documentation

A Docker image (tagged latest) is built 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

Documentation Pages deployment

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

Docker files

The dockerfiles directory contains all needed Dockerfiles to build and deploy https://docs.gitlab.com. It is heavily inspired by Docker's Dockerfile.

Dockerfile	Docker image	Description
Dockerfile.bootstrap	gitlab-docs:bootstrap	Contains all the dependencies that are needed to build the website. If the gems are updated and Gemfile{,.lock} changes, the image must be rebuilt.
Dockerfile.builder.onbuild	gitlab-docs:builder-onbuild	Base image to build the docs website. It uses ONBUILD to perform all steps and depends on gitlab-docs:bootstrap.
Dockerfile.nginx.onbuild	gitlab-docs:nginx-onbuild	Base image to use for building documentation archives. It uses ONBUILD to perform all required steps to copy the archive, and relies upon its parent Dockerfile.builder.onbuild that is invoked when building single documentation archives (see the Dockerfile of each branch)
Dockerfile.archives	gitlab-docs:archives	Contains all the versions of the website in one archive. It copies all generated HTML files from every version in one location.

How to build the images

Although build images are built automatically via GitLab CI/CD, you can build and tag all tooling images locally:

1. Make sure you have Docker installed.

2. Make sure you're in the dockerfiles/ directory of the gitlab-docs repository.

3. 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.