Helm chart releases

Chart Versioning

Major releases

Major releases are for breaking changes and significant milestones in the chart or GitLab release.

We bump the major version number for:

• Significant additions or changes. For example, we add Pages by default or we drop NGINX completely.
• Breaking changes in GitLab or in the charts, requiring manual interaction to upgrade your existing install.
• Major updates in the GitLab image (for example, the release of 12.0.0).

Minor releases

Minor releases will iterate with GitLab image minor releases, and at our own discretion for changes here in the chart.

We will bump it for:

• all minor version updates of GitLab
• changes to our default values in the charts that may increase resource usage (addition of subcharts or pods, additional services or ingresses added)
• Other functionality changes that we feel warrants more visibility.

Patch releases

Patch releases for changes that are considered to be very stable updates to the previous release. This includes patch release of the GitLab image.

We will bump it for:

• Patch releases of the GitLab image
• Any collection of changes that doesn’t cause us to bump the minor or major versions.

Example release scenarios

• (1): If we have two chart versions that both would need to be upgraded to the same image version for a security release, we will just update the newer one. Otherwise automating release logic will be overly complicated. Users can workaround if needed by manually specifying the image version, or upgrading their chart.

Future iteration

While we considered just using the GitLab version as our own, we are not yet in lockstep with GitLab releases to the point where we would make a breaking change here in the chart, and require GitLab to bump the version number to 12 for instance. For now we will move forward with a chart specific version scheme, until we get to the point where we have the charts stable enough that we are comfortable with sharing the same version, and a chart update being a reasonable reason to bump the GitLab core version.

Branches and Tags

For this chart, we propose to follow the same branching strategy as the other main GitLab components.

• A master branch,
• x-x-stable branches that we create from master per minor release.
• x.x.x tags from those stable branches.

The difference between our branch names, and the other GitLab components, is that we will be using the chart’s version in the branch name, rather than the GitLab version.

In general, changes will be merged to master, then cherry-picked into the appropriate branch before release. GitLab image updates will happen as commits in the branches, not in master, as master will follow the latest daily images.

Example timeline of release actions

Related to releasing using the proposed branching strategy

Releasing the chart

Releasing a new version of the chart is handled by the Helm release tasks in the release tools repository.

Releases are done as part of GitLab releases. When necessary, the Distribution team may initiate additional chart releases. The release tool triggers pipelines for packaging and publishing the chart. See the release_chart job in the charts.gitlab.io repository.

Further, the release tool automates management of the:

• CHANGELOG
• Chart versions
• Chart appVersions
• Value of global.gitlabVersion
• GitLab version to Chart version mappings
• Upgrade Stops

Development builds

Development chart versions are being built with every merge to master.

It is possible to track current non-production “development” releases of Helm chart by using devel channel:

helm repo add gitlab-devel https://gitlab.com/api/v4/projects/3828396/packages/helm/devel

and using --devel option for helm pointing to a specific release:

helm install --devel --version 1.2.3-4567 gitlab-devel/gitlab

to list available devel versions:

helm search repo gitlab-devel --devel

Manually releasing the chart

Before manually releasing the chart, ensure all the chart changes you want from master have been picked into the stable branch for the version you will release.

For example, if you want to release version 0.2.1 of the charts, the changes will need to be in 0-2-stable

A ChatOps command exists to tag a release. Run the following command in the relevant release Slack channel (such as #f_release_12_4)

/chatops run helm tag <charts version> <GitLab version>

You can also do it manually, without using the ChatOps command as follows:

1. checkout and setup the release tools repository.

   git clone git@gitlab.com:gitlab-org/release-tools.git
   bundle install

2. Then run the appropriate Helm release task:

   • When you want to release without changing the GitLab app version, call the release task with the new chart version (such as 0.2.1)

     • bundle exec rake release:helm:tag[0.2.1]

   • When you want to release and change both the chart version and the app version (such as 0.2.1 with GitLab 11.0.1)

     • bundle exec rake release:helm:tag[0.2.1,11.0.1]

   You can run the script in dry-run mode which prevents pushes by setting TEST=true in your environment