Versioning

The GitLab Operator uses semver versioning. Version tags should be the semver version string.

Documentation

Operator documentation is available in the doc/ directory.

OLM releases

The GitLab Operator is published to three Operator Lifecycle Manager (OLM) catalogs:

  1. OperatorHub.io
  2. Red Hat community catalog
  3. Red Hat certified catalog

OLM releases are triggered manually by a maintainer after the regular Operator manifest and chart release is complete. The full runbook is in the release issue template.

Upgrade paths for Red Hat catalogs

OLM requires each bundle to declare an explicit upgrade path so that OLM knows which installed versions can be upgraded to the new release. The GitLab Operator uses two strategies:

  • replaces — the standard strategy. The new bundle replaces a specific previous version, forming a linear upgrade chain. Used for ordinary patch and minor releases within an existing channel.
  • skips — used when support for a new OpenShift version is added, which requires creating a new OLM channel. Because replaces requires the target version to already exist in the channel, skips is used instead to declare compatibility without requiring a direct predecessor in that channel. The skipped version(s) gets prunes from the upgrade path.

Red Hat Certification

The release pipeline will contain a certification_upload job when the repository has been tagged with a semver version (i.e. 1.0.0). This job will trigger the Red Hat API to request the image be passed through Red Hat’s certification pipeline. The results of the certification pipeline are published through the Red Hat Connect portal.

It is also possible to pass a release candidate tag (i.e. 1.0.0-rc1) or a beta tag (i.e. 1.0.0-beta1) to trigger the certification_upload job. This will allow the image to go through the Red Hat certification tests, but will not release the images through the production channel (when that functionality has been implemented).

It is also possible to add the certification_upload job to any pipeline by setting the CI variable REDHAT_CERTIFICATION to the value “true”.

In addition, it is possible to run the scripts/redhat_certification.rb script and query the Red Hat API for the status of scan requests that have been submitted. Executing scripts/redhat_certification.rb -s will display a list of images and their current status in the Red Hat certification pipeline.

In order to execute the script independently from GitLab CI one needs to create the REDHAT_API_TOKEN environmental variable. This variable is set to the personal token generated on the Connect portal. The token used by GitLab CI is stored in the 1Password Build vault under the “Red HatCertification Token” entry.

Retagging a release

When a release pipeline fails or other fixes need to be merged before a release can be published, the tag needs to be re-created.

This is done by:

  1. Merge the required fixes into the stable branch.

  2. Delete the tag in canonical.

  3. Delete the tag in the security fork (https://gitlab.com/gitlab-org/security/cloud-native/gitlab-operator).

  4. Delete the tag in the dev fork.

  5. Confirm the CHART_VERSIONS are up to date.

  6. Confirm the appVersion and version in deploy/chart/Chart.yaml is up to date.

  7. Create the tag again on the HEAD of the stable branch.

    Important: The tag must have a description of the following format: Version a.b.c - supports GitLab Charts x, y, z Without this description the tag is not considered by release tools on the next regular release.

  8. Confirm the tag pipeline passes.

  9. Confirm the tag is mirrored to dev.