System requirements

The self-hosted version of GitGuardian is deployed as a Kubernetes application. We recommend installing GitGuardian on an existing cluster using Helm. You can find more information on how to choose your installation method on our dedicated page.

Hardware requirements

Architecture

GitGuardian Platform self-hosted is only compatible with AMD64 architecture.

Existing Kubernetes cluster installation

For sizing recommendations, refer to our Scaling GitGuardian page.

Embedded Kubernetes cluster installation

Component	Required Capacity
CPU	8 cores
Memory	32 GB
Root disk space	300 GB

This installation has some limitations:

• Multi-node support is in beta
• Changing node hostnames is not supported
• Automatic updates not supported
• Support bundles over 100MB in the Admin Console
• Installing on STIG- and CIS-hardened OS images is not supported

More details on Replicated.

Software requirements

Kubernetes for Existing Clusters

For Existing Cluster installations, GitGuardian supports the following Kubernetes versions: 1.25 to 1.32 (we recommend upgrading to 1.32). Version 1.33 is under experimental support.

GitGuardian needs a dedicated namespace.

note

If you plan to install GitGuardian on an OpenShift cluster, please refer to the detailed guidelines for OpenShift cluster installation.

Helm

The Existing Cluster with Helm installation method requires Helm version from 3.13 up to 3.17.

Use a Helm version within this range that aligns with your Kubernetes version to avoid compatibility issues. Refer to the Helm version support policy for the list of compatible versions.

Helm installation also supports some optional custom resources. If you wish to use them, you must have the appropriate controllers and operators:

• IngressController: we provide an example of an ingress controller. You can also configure any other Ingress Controller class. Read our Ingress Configuration topic.
• Istio: we support Istio for traffic routing and end-to-end encryption (sidecars).
• Prometheus Operator: we can deploy ServiceMonitors to expose observability metrics on our application.
• Vault: we allow the use of Vault through external-secrets SecretStore.
• CertManager: we allow certificate management through cert-manager ClusterIssuer.

PostgreSQL

GitGuardian currently supports PostgreSQL 15 to 16.

caution

PostgreSQL versions 13 and 14 are not supported anymore starting 2025.1.0 release. We strongly recommend upgrading to PostgreSQL 16 at your earliest convenience.

You'll need to install the following extensions:

Extension	Usage	Minimal Version
btree_gin	Provides GIN capability to base datatypes (int, timestamp, ...) so all columns can be used in GIN indexes	1.3
pg_trgm	Provides functions and operators enabling fast searching for similar strings using GiST and GIN indexes	1.5
plpgsql	Allows the creation of stored procedures and triggers using the procedural programming language PL/pgSQL	1.0
pgvector	Provides vector similarity search using new types, functions, operators and indexes	0.8.0

Depending on your installation, extensions may already be available. This a the case for the major cloud managed PostgreSQL databases. Otherwise, you might have to carry out some extra actions:

• plpgsql extension is installed by default.
• btree_gin and pg_trgm extensions are available in the postgresql-contrib package.
• pgvector extension is available as a package for Debian, Ubuntu or Yum based OSes. If you are using Docker, you can use the available docker image. You can also install it via the pgxn client.

To make these extensions available in your database, you must run the following commands while connected as a superuser on the database instance:

CREATE EXTENSION IF NOT EXISTS btree_gin;
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE EXTENSION IF NOT EXISTS plpgsql;
CREATE EXTENSION IF NOT EXISTS vector;

For additional guidance on databases, see Configure your database.

For sizing recommendations, refer to our Scaling GitGuardian page.

High Availability and Databases

For large-scale deployments, we recommend using an external PostgreSQL database and leveraging your provider's replication mechanisms for high availability.

Connection Poolers

We recommend avoiding connection poolers (such as PgBouncer) with GitGuardian, as they may cause unexpected behavior or impact performance. Direct connections to PostgreSQL are recommended.

Redis

GitGuardian currently supports Redis 6 and 7, with Redis 7 being the recommended version.

For large-scale deployment, we highly recommend using an external Redis. For sizing recommendations, refer to our Scaling GitGuardian page.

For High Availability, we support Redis Sentinel for Existing cluster.

warning

The Redis instance must be dedicated exclusively to the GitGuardian application. Sharing the instance with other applications may lead to unexpected behavior, data corruption, and performance issues.

info

The FLUSHDB command must be enabled on the Redis instance, as it is essential for the proper functioning of certain features in our application. Ensure that this command is not shadowed in your Redis configuration (e.g., rename-command "FLUSHDB" "").

Be aware that if Redis has an eviction policy set (such as noeviction, allkeys-lru, etc.), and the policy is set to noeviction, Redis will not evict any data. This can cause new writes to fail when the memory limit is reached, so choose your eviction policy carefully.

KOTS

The "Existing cluster with KOTS" installation method is using KOTS. We use the latest KOTS version available to validate our releases. You can find version compatibility on the KOTS compatibility page.

The KOTS Admin Console will have full control over this namespace. The following role needs to be created:

Name:         kotsadm-role
Labels:       kots.io/kotsadm=true
Annotations:  <none>
PolicyRule:
  Resources  Non-Resource URLs  Resource Names  Verbs
  ---------  -----------------  --------------  -----
  *.*        []                 []              [*]

We are using the following objects:

• PersistentVolumeClaims: we are using persistent volume claims for KOTS, workers and the embedded databases.
• IngressController: we can provide a default ingress, an Ingress Controller is needed to handle it.

You need to have the appropriate controllers and operators to handle them.

Operating System

For Embedded Kubernetes cluster installations, please note that these setups are intended primarily for trial or Proof of Concept (PoC) purposes and are not recommended for production use.

Ensure that you adhere to the Replicated and Embedded Cluster system requirements.

note

We strongly recommend applying the latest patches available for your operating system distribution before beginning the installation.

Domain Name requirements

You will need a Fully Qualified Domain Name (FQDN) to install the application (ex: gitguardian.mycorp.local). This cannot be an IP. You will also need a TLS certificate for HTTPS access or use the default self-signed certificates.