Skip to content

docs.gitlab.com release 18.2 (July, 2025)

Tasks for all releases

Documentation for handling the docs release is available.

Terminology

The following terms are used throughout this document:

  • Stable branch: This is the branch that matches the GitLab version being released. For example, for GitLab 17.2, the stable branch is 17.2.

On Monday the week of the release

  1. Ensure required tools are installed and up-to-date. In the root path of the docs-gitlab-com repository:

    • Update your local clone:

      make update

    • Install and update all project dependencies:

      make setup

    • Ensure you're authenticated with glab:

      $ glab auth status

gitlab.com
✓ Logged in to gitlab.com as <username> (<$HOME>/.config/glab-cli/config.yml)
✓ Git operations for gitlab.com configured to use ssh protocol.
✓ API calls for gitlab.com are made over https protocol.
✓ REST API Endpoint: https://gitlab.com/api/v4/
✓ GraphQL Endpoint: https://gitlab.com/api/graphql/
✓ Token: **************************

  2. Cross-link to the main MR for the release post: Release post - GitLab 18.2 (gitlab-com/www-gitlab-com!140175 - merged) (Need help finding the MR?)

  3. In this issue, create separate threads for the retrospective, and add items as they appear:

    ## :+1: What went well this release?
## :-1: What didn't go well this release?
## :chart_with_upwards_trend: What can we improve going forward?

  4. Archive the older version (or versions, if it's a major release) that we no longer need to host on docs.gitlab.com. The script doesn't remove the older version yet, it just adds it to the archive: docs archives (gitlab-docs-archives) repository:

    make create-archive-branch

    Do NOT create a merge request. After a couple of minutes, the version will be deployed. The release number shown in the script is an older release. For example, if the release version is GitLab 18.0, the command deploys to: archives.docs.gitlab.com/17.9/. You can visit https://archives.docs.gitlab.com/<version> to verify.

On the Thursday of the release, or the day after

After the release post is live, or the day after:

  1. In the root path of the docs-gitlab-com repository, use the create-stable-branch Make target to create the stable branch by replacing X.Y with the new version:

    make create-stable-branch VERSION=X.Y

    Creating the stable branch on the release day is ideal, though this might not always be possible depending on your timezone. Issue 248 exists to automate stable branch creation.

    • You can track the progress of the stable branch pipeline from the pipelines list.
    • When the stable branch pipeline completes, the new version will be available at docs.gitlab.com/X.Y: https://docs.gitlab.com/18.2/. Verify that the new release is functional, then proceed to the next step.

  2. In the root path of the docs-gitlab-com repository, use the create-release-merge-request Make target to create the release merge request by replacing X.Y with the new version. This merge request updates the version dropdown list for all online versions:

     make create-release-merge-request VERSION=X.Y
    1. Verify that the merge request Docs release 18.2 (!992 - merged):
      • Has the ~release label.
      • Includes only the following in the Changes tab:
        • .gitlab/ci/docker-images.gitlab-ci.yml
        • content/versions.json

  3. Ask in Slack in #tw-team for someone to review and merge the release merge request for you.

  4. After the deployment completes, open docs.gitlab.com in a browser. Confirm both the latest version and the correct pre-release version are listed in the version dropdown list. Note that it may take up to 5 minutes for the deployed changes to appear on the website due to caching.

    The next release version appears as the default version in docs.gitlab.com. Issue 324 exists to make the latest stable release the default.

  5. Check the version dropdown list to ensure all versions of the docs are visible and their version dropdown lists have the expected versions.

    • Versions hosted on docs.gitlab.com should show the same version options as the pre-release site.
    • Versions hosted on archives.docs.gitlab.com should only show their own version and a link back to the archives page.
      • This applies to GitLab 15.6 and later. Earlier versions might have broken links in the version dropdown list. This will eventually be resolved as the earlier versions are phased out.

  6. Share the following message in the #tw-team channel:

    :mega: The docs <version> release is complete. If you have any feedback about this release, add it to the retro thread in <this issue>.

Post-deployment checklist

After the docs release is complete:

  1. Major releases only. Update OutdatedVersions.yml with the latest outdated version.
  2. Improve this checklist.
  3. Create a release issue for the next release, and assign it to the TW who completed the release post structural check for the current milestone.

Helpful links

Edited by Lorena Ciutacu