Upgrade Helm

danger

Do not roll back or downgrade without consulting our support team first. Certain scenarios may necessitate restoring the database from a pre-upgrade backup due to the complexity of reversing some database migrations.

caution

Prior to upgrading, ensure you back up your PostgreSQL database. For detailed instructions, refer to the Backup page.

Upgrading to 2025.10

If you are using an air gap deployment: This release now uses a non-Bitnami chart and Docker image for the MinIO subchart (which supports the log collector feature). This change implies minor modifications to your values.yaml file:

Modify your Helm values file:

• Update loki-minio.image.repository from gitguardian/wolfi/minio-bitnami to gitguardian/wolfi/minio.
• Update loki-minio.image.tag from 0.20250723 to 0.20250907.
• Rename parameter loki-minio.image.pullPolicy to loki-minio.image.imagePullPolicy.

Upgrading to 2025.8

If you are using an air gap deployment: This release introduces a new image.registry parameter in Helm values to support the Log Collector system. This parameter specifies the location of the GitGuardian images for the Log Collector components (Loki, MinIO, Fluent Bit) and is separate from the main imageRegistry parameter.

Add the image.registry to your Helm values file:

global:
  imageRegistry: docker.internal/example/path # Location of the GitGuardian images
  image:
    registry:  docker.internal/example/path # Location of the GitGuardian images (same as imageRegistry)

Find all image and tag names on the Air Gap Install page.

Upgrading to 2025.7

Machine Learning engine is now enabled by default. Ensure your infrastructure meets the ML requirements.

Upgrading to 2025.6

GitGuardian 2025.6 now requires Kubernetes 1.28 as the minimum supported version. However, Kubernetes 1.28 is no longer receiving active or maintenance support from the Kubernetes project (support ended in October 2024).

We strongly recommend upgrading to Kubernetes 1.32 for optimal security and stability. Kubernetes 1.32 is actively supported until December 2025 and will receive maintenance support until February 2026.

For more information:

• Kubernetes end-of-life schedule
• GitGuardian system requirements

Upgrading to 2025.5

Air gap deployment? We've renamed images in this release. See below and find all image and tag names on the Air Gap Install page.

This change involves renaming the following images:

• gitguardian/prm-static-chainguard-fips to gitguardian/prm-static-chainguard
• gitguardian/prm-app-fips to gitguardian/prm-app-chainguard

Upgrading to 2025.4

Please install the PostgreSQL pgvector extension to enable vector similarity search. This is essential for upcoming features leveraging our internal machine learning engine. Follow the installation instructions to ensure compatibility.

Air gap deployment? We've added new images in this release. The new images are for the log collection system, which includes:

• Fluent Bit (log collector)
• Loki (log aggregation)
• MinIO (object storage for logs)

Find all image and tag names on the Air Gap Install page.

Upgrading to 2025.3

The 2025.3 release introduces a breaking change in the naming registry URL, including the path and image names. If you are downloading our images in a private registry (refer to our air gap documentation), make sure to update your tooling, as well as the image names and paths in your Helm values file.

Change registry URL

• Old: proxy.replicated.com/proxy/gitguardian/513715405986.dkr.ecr.us-west-2.amazonaws.com
• New: proxy.replicated.com/proxy/gitguardian/docker.io

Image path and name changes

• /prm/static-chainguard ➔ /gitguardian/prm-static-chainguard-fips
• /prm/app-chainguard ➔ /gitguardian/prm-app-chainguard-fips
• /prm/helm-tooling ➔ /gitguardian/prm-helm-tooling
• /services/nginx-unprivileged ➔ /nginxinc/nginx-unprivileged
• /ml-detector/ml-secret-engine/app-chainguard ➔ /gitguardian/ml-secret-engine-app-chainguard-fips

Change registry URL

• Old: registry.replicated.com
• New: proxy.replicated.com/proxy/gitguardian/docker.io

Image path and name changes

• /gitguardian/replicated-sdk ➔ /replicated/replicated-sdk

Upgrading to 2025.1

Database Deprecation Notice: PostgreSQL 13 & 14 are no longer supported. Learn why upgrading to PostgreSQL 16 is recommended in our engineering blog.

Upgrade Considerations: This release includes a background migration that may take up to 1 hour post-upgrade. It improves query execution speed and search performance. If upgrading from an older version, multiple upgrades may trigger a retry message—wait 1 hour before retrying.

Upgrading to 2024.12

The 2024.12 release introduces the following breaking change:

The front.ingress parameter has been renamed to ingress to improve consistency and standardize the ingress object across the Helm chart.

Please find more details on the Helm values page here.

Be sure to update your Helm values file accordingly.

Run preflight checks 🚦

Requirements

Preflight checks are critical for a successful installation. The following rules apply:

• ❌ Preflight Check Failures: If preflight checks fail, the upgrade must not continue until the targeted environment meets all requirements. Please reach out to our support team if needed.
• ⚠️ Preflight Check Warnings: If preflight checks return warnings, the installation can proceed, but it is recommended that you address these warnings to comply with our recommendations.

We strongly advise you to run our preflight script to ensure your existing cluster meets Gitguardian's requirements.

Retrieve the script from our public repository here

Specify an existing Kubernetes namespace using the -n option. If not specified, the script will run in your default namespace.

./preflights.sh -n <namespace> oci://registry.replicated.com/gitguardian/gitguardian -f local-values.yaml

Upgrading the GitGuardian application

Log in to the registry with the following command:

helm registry login registry.replicated.com --username your.name@yourcompany.com

Upgrade the GitGuardian application to the latest version in the Kubernetes cluster and namespace where it's installed:

helm upgrade <release-name> -n <namespace> oci://registry.replicated.com/gitguardian/gitguardian -f local-values.yaml

Replace <release-name> with the name used during the initial installation (use helm ls to find it). If needed, specify the namespace with -n (default namespace is used if not specified).

This will upgrade your application to the latest version. To upgrade to a specific version, use the --version flag:

helm upgrade <release-name> -n <namespace> oci://registry.replicated.com/gitguardian/gitguardian --version 2024.x.y -f local-values.yaml

Upgrading the GitGuardian application in Airgap

Follow these steps to upgrade a Helm-based installation in an air-gapped environment:

1. Log in to the Helm registry:

   helm registry login registry.replicated.com --username your.name@yourcompany.com

2. Download the Helm chart locally (replace with the desired version as needed):

   helm fetch oci://registry.replicated.com/gitguardian/gitguardian
   # this will download a file like gitguardian-<version>.tgz

3. Authenticate Docker to the Replicated proxy to pull images (replace <your_licenseID>):

   LICENSE_ID="<your_licenseID>"; \
   echo "{\"auths\": {\"proxy.replicated.com\": {\"auth\": \"$(echo -n \"${LICENSE_ID}:${LICENSE_ID}\" | base64)\"}, \"registry.replicated.com\": {\"auth\": \"$(echo -n \"${LICENSE_ID}:${LICENSE_ID}\" | base64)\"}}}" > ~/.docker/config.json

4. Pull the required images for the target release, then upload them to your private registry. Refer to the image list on the Airgap Install page. You can use docker or skopeo to transfer images.

   Image architecture

   All GitGuardian images are multi-architecture. You do not need to pass --platform when pulling them; the correct variant is selected automatically based on the host architecture.

5. Run preflight checks against the local chart archive:

   ./preflights.sh -n <namespace> gitguardian-<version>.tgz -f local-values.yaml

6. Upgrade using the local chart archive:

   helm upgrade <release-name> --timeout 30m -n <namespace> gitguardian-<version>.tgz -f local-values.yaml

Replace <release-name>, <namespace>, and <version> accordingly. Ensure your local-values.yaml points to your private image registry as described in the Airgap Install page.

Updating application configuration

Modify the application configuration with an updated values file using the helm upgrade command. Stick to the same version using the --version flag:

helm upgrade <release-name> -n <namespace> oci://registry.replicated.com/gitguardian/gitguardian --version 2024.x.y -f local-values.yaml

Replace <release-name> with the name used during the initial installation (use helm ls to find it). If needed, specify the Kubernetes namespace with -n (default namespace is used if not specified).

Additional notes

• Pod update strategy

The goal is to find a balance between service continuity and available resources on the cluster. You can define which update strategy to use during an upgrade / update.

This configuration is possible for celeryWorkers (celeryWorkers.worker.updateStrategy) and webapps (webapps.app.updateStrategy).

If not defined, this default strategy applies:

• If less than 3 replicas

type: RollingUpdate
rollingUpdate:
	maxUnavailable: 50%
	maxSurge: 50%

• Else

type: RollingUpdate
rollingUpdate:
	maxUnavailable: 25%
	maxSurge: 25%