Skip to content

Docs release can block backport MRs shortly before the release

The Hugo build tests in upstream pipelines are set up to use the same version of the Docs site as the branch being pushed to in the upstream projects: https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/docs.gitlab-ci.yml?ref_type=heads#L107

For example, if you're pushing an MR to 17-11-stable-ee in gitlab, we need to build Hugo and run tests with the 17.11 branch of the Hugo website. This ensures any tests added to Hugo in subsequent releases don't cause older docs to fail.

However, this creates a blocking problem in this scenario, using 18.3 as an example:

  1. gitlab branch 18-3-stable-ee is cut on a Monday before the release date
  2. gitlab needs to backport something to 18.3 on Tuesday
  3. docs branch for 18.3 does not exist until the actual release date (Thursday)
  4. the job fails like this: https://gitlab.com/gitlab-org/security/gitlab/-/jobs/11091154585

A few ideas to fix this:

  1. Have the docs hugo_build job fallback to main if the branch to match gitlab's doesn't exist yet
  2. Create the docs release branch earlier (when? the cutoff varies for gitlab), but hold on the user-facing parts of the release (updating versions.json, which updates the Versions dropdown menu) until the actual release (3rd Thursday)

Workaround

We can create the branch earlier than the release date, we just can't use our release tooling as usual if we do this.

  1. Create the missing docs branch manually
  2. Handle the subsequent steps of the release manually

MRs

We'll have to fix this in multiple projects:

We do not need to update operator since we only build with main in that project.

Edited by Sarah German