Skip to content

GitLab package development and maintenance📜

Upgrade workflow📜

  1. Review every upstream GitLab application and Helm-chart release note between the current and target versions. For a major release, also review the deprecations, breaking-change guide, version-specific upgrade notes, and required upgrade stops.
  2. Verify the application-to-chart mapping in the upstream version mapping.
  3. Diff the old and new upstream chart archives. The vendored upstream archive is intentionally unmodified; Big Bang changes live in the outer wrapper chart.
  4. Update chart/Chart.yaml:
  5. Big Bang composite chart version.
  6. appVersion.
  7. upstream GitLab dependency.
  8. bb-common and Gluon dependency versions.
  9. every conditional image annotation.
  10. Update Verified Publisher CNG GitLab images, supporting Iron Bank images, and all affected values. Remove deleted values that no longer configure a supported service; do not mistake a retained no-op install: false value for an external-service configuration.
  11. Run helm dependency update chart and commit Chart.lock plus all packaged dependency archives.
  12. Update CHANGELOG.md, migration/operational docs, tests, and Renovate configuration. Major upgrade notices belong in the merge-request description; link a longer migration document when needed.
  13. Regenerate the root README.md last with the package’s Gluon/helm-docs workflow.
  14. Run lint, template, unit, policy, and schema validation before k3d testing.

Useful local checks:

helm dependency list chart
helm lint chart
yq '.addons.gitlab.values' tests/test-values.yaml | \
  helm template gitlab chart --namespace gitlab -f - >/tmp/gitlab.yaml
helm unittest -f 'unittests/*_test.yaml' chart

A bare default render is expected to fail GitLab’s external-service checks. Public defaults intentionally do not supply PostgreSQL, Redis/Valkey, or object storage connections; render with a complete consumer profile or the extracted internal test profile above.

GitLab 19 service architecture📜

GitLab chart 10 no longer contains PostgreSQL, Redis, or MinIO. The GitLab package deploys no replacement workloads or custom resources. Consumers must provide externally managed PostgreSQL 17, a supported Redis or Valkey release, and GitLab-supported external object storage through the upstream values and Secrets.

Big Bang CI provisions its disposable dependencies as independent umbrella HelmReleases; this is an internal test environment, not a supported consumer development or production persistence topology. The test contract is:

  • The Big Bang maintained cloudnative-pg operator HelmRelease in bigbang, targeting workload namespace cloudnative-pg.
  • The Big Bang maintained wrapper chart as the independent postgresql HelmRelease in bigbang, targeting workload namespace postgresql. Its package.configMaps placeholder is replaced in memory by a Flux Kustomize post-renderer with the single PostgreSQL 17 Cluster/postgresql resource; no placeholder ConfigMap is installed. The HelmRelease waits for the Cluster’s Ready=True condition, and CloudNativePG generates the postgresql-app credentials. This test operand is not part of the GitLab chart.
  • Big Bang maintained redis and garage HelmReleases in bigbang, targeting their matching workload namespaces.
  • postgresql-rw.postgresql.svc.cluster.local:5432.
  • redis-master.redis.svc.cluster.local:6379.
  • http://garage.garage.svc.cluster.local:3900.

Both package test-value files carry the generic dependency definitions required by package CI and must stay aligned with the umbrella test track. They render independent HelmReleases through the umbrella’s generic packages mechanism; they are not GitLab chart dependencies or consumer defaults. The ambient profile enrolls each dependency namespace and explicitly permits HBONE port 15008 in the PostgreSQL and Redis wrapper policies; Garage receives HBONE policy injection from bb-common. GitLab itself consumes only the external-service connections and dependsOn ordering. Do not add maintained charts, operators, database custom resources, or dependency Secrets to the GitLab chart.

Redis and CloudNativePG must generate their source credentials. The CI-only sync-gitlab-ci-credentials Kyverno policy clones those Secrets into the GitLab namespace and transforms garage/garage-gitlab-credentials into Rails, Registry, and Toolbox backup configuration. Do not restore the umbrella addons.gitlab.database, addons.gitlab.redis.password, or addons.gitlab.objectStorage credential wrappers; they would create competing Secrets. Garage supports externally managed credential Secrets, but these disposable test profiles keep fixed inline credentials until the maintained chart supports generation.

See gitlab-19-upgrade.md for the consumer migration requirements that supplement GitLab’s upstream procedure.

k3d validation📜

Test a clean install and, when a normal upgrade is supported, the CI-style upgrade from the current main release. GitLab 19’s bundled-service removal requires a separate staged test because a one-step Helm upgrade cannot prove database or object-data preservation.

For every release, validate:

  1. HelmRelease and all expected workloads become Ready.
  2. The GitLab Help page reports the target version.
  3. Login, profile update, group/project creation, Git clone, commit, and push.
  4. Personal access token creation through the UI or Rails runner. Do not use OAuth Resource Owner Password Credentials; GitLab 19 removes that grant.
  5. Registry login, push, pull, and delete against the configured object store.
  6. A runner pipeline completes and its artifact can be downloaded.
  7. LFS/uploads/packages and other enabled object types can round-trip data.
  8. Toolbox backup and restore work with the selected object store.
  9. Monitoring targets and logging work when those integrations are enabled.
  10. Sidecar and ambient profiles render and reconcile with NetworkPolicy and authorization enabled.

For the GitLab 19 manual upgrade proof:

  1. Deploy GitLab 18.11/chart 9.11 and seed a user, repository, Registry image, pipeline artifact, and object-storage data.
  2. Install external PostgreSQL 17, Redis or Valkey, and object storage before changing GitLab.
  3. Back up, retain old PVCs, repoint GitLab 18.11 with migrations disabled, restore, re-enable migrations, and verify all seeded data.
  4. Upgrade to GitLab 19/chart 10 with the removed values deleted and every still-supported override preserved, especially immutable StatefulSet values such as the existing Gitaly persistence size.
  5. Re-run the full functional and backup checks.

If the package CI cannot safely express this staged migration, retain clean install validation, document the k3d proof, and use the exact skip-job-upgrade label only with maintainer authorization.

Big Bang wrapper modifications📜

The upstream GitLab archive in chart/charts is unpatched. Big Bang behavior is implemented by:

  • chart/templates/_certificates.tpl for the Verified Publisher CNG UBI certificate paths and configurable init-container security context.
  • chart/templates/bigbang/ for routes, NetworkPolicy, Istio, OpenShift, certificate Secrets, and tests.
  • chart/values.yaml for Verified Publisher CNG GitLab images, supporting Iron Bank images, hardened security contexts, Big Bang routes, and reduced CI resources.
  • chart/templates/tests/ and chart/tests/ for Gluon/Cypress and script tests.

When updating upstream, confirm the named templates overridden by the outer chart still exist and have compatible call signatures. Never patch a packaged dependency archive by hand; make the change in the outer wrapper or contribute it upstream.

README and release metadata📜

The root README is generated. Make documentation comments in chart/values.yaml clear and run the Gluon-supported helm-docs command only after values and dependencies are final. Confirm the generated README points to the exact upstream chart dependency and that tests/images.txt is absent.

Keep a single coherent changelog entry for the package version. Image-only Renovate changes should remain grouped, while architectural changes and manual migration requirements must be called out explicitly in the merge request.