Skip to content

Update Hugo to v0.150.1

Hugo update checklist

Because we run Hugo build tests in every docs content repository, updating Hugo requires multiple MRs. Follow the checklists below to update Hugo for local development, upstream build tests, and production.

Create a test build image

First, follow the steps below to generate a new docs-gitlab-com-builder:hugo Docker image that includes the new Hugo version. We'll need this for testing the upgrade.

If there's already a published Docker image for the new version, you can move onto Test the new Hugo version locally.

  1. Review Hugo release notes to find the latest version.
  2. Update HUGO_VERSION_NEXT in .gitlab-ci.yml to reference the new version.
  3. Create an MR with just this change. Get it reviewed and merged (example MR).
  4. Trigger the Build docker images pipeline (Manual).
    • Verify the test job, test:image:docs-gitlab-com-builder, completes successfully.
    • Manually trigger the image:docs-gitlab-com-builder job to publish the image.

MR link: !1347 (merged)

Test the new Hugo version locally

  1. Review Hugo release notes and check for breaking changes in any versions that have been released since our last update. This is also a good opportunity to look for new features that may be useful on our project.
  2. Update your local Hugo version: in mise.toml, update hugo-extended to the new version.
  3. Test locally:
    • Run make setup and make view to set up and run the site locally.
    • Verify that pages are rendered correctly. Be sure to check pages that use different templates: Homepage, /404.html, /search, /archives.
    • Verify that non-English content builds as expected. If needed, enable a non-English language in hugo.yaml to test.
  4. Set HUGO_VERSION in .gitlab-ci.yml to the new version.
  5. Create a draft MR with the changes to gitlab-ci.yml and mise.toml. This will eventually update the production site.
  6. Check the log for the build:compile_site job for any deprecation notices or warnings, and verify the end-to-end pipeline finishes successfully.
  7. Hold onto this MR as a draft for now. Do not merge yet.

MR link: !1348 (merged)

If breaking changes are detected, you will need to create a compatibility plan before proceeding. Running a different version of Hugo in docs-gitlab-com and the product repositories could result in failed pipelines due to failing Hugo build jobs.

Update tests in product repositories

Update all product repositories to use the new Hugo build image. See below for example MRs:

In each repository, update CI config to reference the new docs-gitlab-com-builder:hugo image.

Verify that the Hugo build job in each project still passes, then request a review from a member of the DocOps group.

Update the production site

After the product repository MRs have merged, we can update the production site.

Do this when you will be online for at least a few more hours, just in case we need to troubleshoot a problem or roll back the update.

    • Remove the draft status from your docs-gitlab-com MR created previously.
    • Rebase the MR.
    • Run a new pipeline and verify all jobs pass.
    • Get a final review and merge. 🎉
Edited by Sarah German