• Configure Host settings
  • hostSuffix
• Configure Horizontal Pod Autoscaler settings
• Configure PodDisruptionBudget settings
• Configure CronJob settings
• Configure Monitoring settings
• Configure Ingress settings
  • Ingress Path
  • Cloud provider LoadBalancers
  • global.ingress.configureCertmanager
  • global.ingress.useNewIngressForCerts
• GitLab Version
• Adding suffix to all image tags
• Configure PostgreSQL settings
  • PostgreSQL per chart
  • PostgreSQL SSL
  • PostgreSQL load balancing
  • Configure multiple database connections
• Configure Redis settings
  • Configure Redis chart-specific settings
  • Redis Sentinel support
    • Redis Sentinel password support
  • Multiple Redis support
  • Specify secure Redis scheme (SSL)
  • Password-less Redis Servers
• Configure Registry settings
  • notifications
• Configure Gitaly settings
  • Gitaly hosts
    • Internal
    • External
    • Mixed
  • authToken
  • Deprecated Gitaly settings
  • TLS settings
• Configure Praefect settings
  • Enable Praefect
  • Global settings for Praefect
• Configure MinIO settings
• Configure appConfig settings
  • General application settings
    • Content Security Policy
    • defaultProjectsFeatures
  • Gravatar/Libravatar settings
  • Hooking Analytics services to the GitLab instance
  • Consolidated object storage
  • Specify buckets
    • storage_options
  • LFS, Artifacts, Uploads, Packages, External MR diffs, and Dependency Proxy
    • connection
    • when (only for External MR Diffs)
    • cdn (only for CI Artifacts)
  • Incoming email settings
  • KAS settings
    • Custom secret
    • Custom URLs
    • External KAS
    • TLS settings
  • Suggested Reviewers settings
  • LDAP
    • Disable LDAP web sign in
    • Using a custom CA or self signed LDAP certificates
  • DuoAuth
  • Configure the GitLab Duo secret key
  • OmniAuth
    • providers
  • Cron jobs related settings
  • Sentry settings
  • gitlab_docs settings
  • Smartcard Authentication settings
  • Sidekiq routing rules settings
• Configure Rails settings
• Configure Workhorse settings
  • Bootsnap Cache
• Configure GitLab Shell
  • Port
  • TCP proxy protocol
• Configure GitLab Pages
• Configure Webservice
  • workerTimeout
• Custom Certificate Authorities
• Application Resource
• GitLab base image
• Service Accounts
• Annotations
• Node Selector
• Labels
  • Common Labels
  • Pod
  • Service
• Tracing
• extraEnv
• extraEnvFrom
• Configure OAuth settings
• Kerberos
  • Dedicated port for Kerberos
  • LDAP custom allowed realms
• Outgoing email
• Platform
• Affinity
• Pod Priority and Preemption
• Log rotation
• Jobs
• Traefik

Configure charts using globals

To reduce configuration duplication when installing our wrapper Helm chart, several configuration settings are available to be set in the global section of values.yaml. These global settings are used across several charts, while all other settings are scoped within their chart. See the Helm documentation on globals for more information on how the global variables work.

• Hosts
• Ingress
• GitLab Version
• PostgreSQL
• Redis
• Registry
• Gitaly
• Praefect
• MinIO
• appConfig
• Rails
• Workhorse
• GitLab Shell
• Pages
• Webservice
• Custom Certificate Authorities
• Application Resource
• GitLab base image
• Service Accounts
• Annotations
• Tracing
• extraEnv
• extraEnvFrom
• OAuth
• Kerberos
• Outgoing email
• Platform
• Affinity
• Pod priority and preemption
• Log rotation
• Jobs
• Traefik

Configure Host settings

The GitLab global host settings are located under the global.hosts key.

global:
  hosts:
    domain: example.com
    hostSuffix: staging
    https: false
    externalIP:
    gitlab:
      name: gitlab.example.com
      https: false
    registry:
      name: registry.example.com
      https: false
    minio:
      name: minio.example.com
      https: false
    smartcard:
      name: smartcard.example.com
    kas:
      name: kas.example.com
    pages:
      name: pages.example.com
      https: false
    ssh: gitlab.example.com

hostSuffix

The hostSuffix is appended to the subdomain when assembling a hostname using the base domain, but is not used for hosts that have their own name set.

Defaults to being unset. If set, the suffix is appended to the subdomain with a hyphen. The example below would result in using external hostnames like gitlab-staging.example.com and registry-staging.example.com:

global:
  hosts:
    domain: example.com
    hostSuffix: staging

Configure Horizontal Pod Autoscaler settings

The GitLab global host settings for HPA are located under the global.hpa key:

Configure PodDisruptionBudget settings

The GitLab global host settings for PDB are located under the global.pdb key:

Configure CronJob settings

The GitLab global host settings for CronJobs are located under the global.batch.cronJob key:

Configure Monitoring settings

The GitLab global settings for ServiceMonitors and PodMonitors are located under the global.monitoring key:

Configure Ingress settings

The GitLab global host settings for Ingress are located under the global.ingress key:

Sample configurations for various cloud providers can be found in the examples folder.

• AWS
• GKE

Ingress Path

This chart employs global.ingress.path as a means to assist those users that need to alter the definition of path entries for their Ingress objects. Many users have no need for this setting, and should not configure it.

For those users who need to have their path definitions end in /* to match their load balancer / proxy behaviors, such as when using ingress.class: gce in GCP, ingress.class: alb in AWS, or another such provider.

This setting ensures that all path entries in Ingress resources throughout this chart are rendered with this. The only exception is when populating the gitlab/webservice deployments settings, where path must be specified.

Cloud provider LoadBalancers

Various cloud providers’ LoadBalancer implementations have an impact on configuration of the Ingress resources and NGINX controller deployed as part of this chart. The next table provides examples.

global.ingress.configureCertmanager

Global setting that controls the automatic configuration of cert-manager for Ingress objects. If true, relies on certmanager-issuer.email being set.

If false and global.ingress.tls.secretName is not set, this will activate automatic self-signed certificate generation, which creates a wildcard certificate for all Ingress objects.

If you wish to use an external cert-manager, you must provide the following:

• gitlab.webservice.ingress.tls.secretName
• registry.ingress.tls.secretName
• minio.ingress.tls.secretName
• global.ingress.annotations

global.ingress.useNewIngressForCerts

Global setting that changes the behavior of the cert-manager to perform the ACME challenge validation with a new Ingress created dynamically each time.

The default logic (when global.ingress.useNewIngressForCerts is false) reuses existing Ingresses for validation. This default is not suitable in some situations. Setting the flag to true will mean that a new Ingress object is created for each validation.

global.ingress.useNewIngressForCerts cannot be set to true when used with GKE Ingress Controllers. For full details on enabling this, see release notes.

GitLab Version

The GitLab version used in the default image tag for the charts can be changed using the global.gitlabVersion key:

--set global.gitlabVersion=11.0.1

This impacts the default image tag used in the webservice, sidekiq, and migration charts. Note that the gitaly, gitlab-shell and gitlab-runner image tags should be separately updated to versions compatible with the GitLab version.

Adding suffix to all image tags

If you wish to add a suffix to the name of all images used in the Helm chart, you can use the global.image.tagSuffix key. An example of this use case might be if you wish to use fips compliant container images from GitLab, which are all built with the -fips extension to the image tag.

--set global.image.tagSuffix="-fips"

Configure PostgreSQL settings

The GitLab global PostgreSQL settings are located under the global.psql key. GitLab is using two database connections: one for main database and one for ci. By default, they point to the same PostgreSQL database.

The values under global.psql are defaults and are applied to both database configurations. If you want to use two databases, you can specifiy the connection details in global.psql.main and global.psql.ci.

global:
  psql:
    host: psql.example.com
    # serviceName: pgbouncer
    port: 5432
    database: gitlabhq_production
    username: gitlab
    applicationName:
    preparedStatements: false
    databaseTasks: true
    connectTimeout:
    keepalives:
    keepalivesIdle:
    keepalivesInterval:
    keepalivesCount:
    tcpUserTimeout:
    password:
      useSecret: true
      secret: gitlab-postgres
      key: psql-password
      file:
    main: {}
      # host: postgresql-main.hostedsomewhere.else
      # ...
    ci: {}
      # host: postgresql-ci.hostedsomewhere.else
      # ...

PostgreSQL per chart

In some complex deployments, it may be desired to configure different parts of this chart with different configurations for PostgreSQL. As of v4.2.0, all properties available within global.psql can be set on a per-chart basis, for example gitlab.sidekiq.psql. The local settings will override global values when supplied, inheriting any not present from global.psql, with the exception of psql.load_balancing.

PostgreSQL load balancing will never inherit from the global, by design.

PostgreSQL SSL

If you want to connect GitLab with a PostgreSQL database over mutual TLS, create a secret containing the client key, client certificate and server certificate authority as different secret keys. Then describe the secret’s structure using the global.psql.ssl mapping.

global:
  psql:
    ssl:
      secret: db-example-ssl-secrets # Name of the secret
      clientCertificate: cert.pem    # Secret key storing the certificate
      clientKey: key.pem             # Secret key of the certificate's key
      serverCA: server-ca.pem        # Secret key containing the CA for the database server

You may also need to set extraEnv values to export environment values to point to the correct keys.

global:
  extraEnv:
      PGSSLCERT: '/etc/gitlab/postgres/ssl/client-certificate.pem'
      PGSSLKEY: '/etc/gitlab/postgres/ssl/client-key.pem'
      PGSSLROOTCERT: '/etc/gitlab/postgres/ssl/server-ca.pem'

PostgreSQL load balancing

This feature requires the use of an external PostgreSQL, as this chart does not deploy PostgreSQL in an HA fashion.

The Rails components in GitLab have the ability to make use of PostgreSQL clusters to load balance read-only queries.

This feature can be configured in two fashions:

• Using a static lists of hostnames for the secondaries.
• Using a DNS based service discovery mechanism.

Configuration with a static list of is straight forward:

global:
  psql:
    host: primary.database
    load_balancing:
       hosts:
       - secondary-1.database
       - secondary-2.database

Configuration of service discovery can be more complex. For a complete details of this configuration, the parameters and their associated behaviors, see Service Discovery in the GitLab Administration documentation.

global:
  psql:
    host: primary.database
    load_balancing:
      discover:
        record:  secondary.postgresql.service.consul
        # record_type: A
        # nameserver: localhost
        # port: 8600
        # interval: 60
        # disconnect_timeout: 120
        # use_tcp: false
        # max_replica_pools: 30

Further tuning is also available, in regards to the handling of stale reads. The GitLab Administration documentation covers these items in detail, and those properties can be added directly under load_balancing.

global:
  psql:
    load_balancing:
      max_replication_difference: # See documentation
      max_replication_lag_time:   # See documentation
      replica_check_interval:     # See documentation

Configure multiple database connections

In GitLab 16.0, GitLab defaults to using two database connections that point to the same PostgreSQL database.

Configure Redis settings

The GitLab global Redis settings are located under the global.redis key.

By default we use an single, non-replicated Redis instance. If a highly available Redis is required, we recommend using an external Redis instance.

You can bring an external Redis instance by setting redis.install=false, and following our advanced documentation for configuration.

global:
  redis:
    host: redis.example.com
    serviceName: redis
    port: 6379
    auth:
      enabled: true
      secret: gitlab-redis
      key: redis-password
    scheme:

Configure Redis chart-specific settings

Settings to configure the Redis chart directly are located under the redis key:

redis:
  install: true
  image:
    registry: registry.example.com
    repository: example/redis
    tag: x.y.z

Refer to the full list of settings for more information.

Redis Sentinel support

The current Redis Sentinel support only supports Sentinels that have been deployed separately from the GitLab chart. As a result, the Redis deployment through the GitLab chart should be disabled with redis.install=false. The Kubernetes Secret containing the Redis password will need to be manually created before deploying the GitLab chart.

The installation of an HA Redis cluster from the GitLab chart does not support using sentinels. If sentinel support is desired, a Redis cluster needs to be created separately from the GitLab chart install. This can be done inside or outside the Kubernetes cluster.

An issue to track the supporting of sentinels in a GitLab deployed Redis cluster has been created for tracking purposes.

redis:
  install: false
global:
  redis:
    host: redis.example.com
    serviceName: redis
    port: 6379
    sentinels:
      - host: sentinel1.example.com
        port: 26379
      - host: sentinel2.exeample.com
        port: 26379
    auth:
      enabled: true
      secret: gitlab-redis
      key: redis-password

All the prior Redis attributes in the general configure Redis settings continue to apply with the Sentinel support unless re-specified in the table above.

Redis Sentinel password support

redis:
  install: false
global:
  redis:
    host: redis.example.com
    serviceName: redis
    port: 6379
    sentinels:
      - host: sentinel1.example.com
        port: 26379
      - host: sentinel2.example.com
        port: 26379
    auth:
      enabled: true
      secret: gitlab-redis
      key: redis-password
    sentinelAuth:
      enabled: false
      secret: gitlab-redis-sentinel
      key: sentinel-password

global.redis.sentinelAuth can be used to configure a Sentinel password for all Sentinel instances.

Note that sentinelAuth cannot be overridden with Redis instance-specific settings or global.redis.redisYmlOverride.

Multiple Redis support

The GitLab chart includes support for running with separate Redis instances for different persistence classes, currently:

Any number of the instances may be specified. Any instances not specified will be handled by the primary Redis instance specified by global.redis.host or use the deployed Redis instance from the chart. The only exception is for the GitLab agent server (KAS), which looks for Redis configuration in the following order:

1. global.redis.kas
2. global.redis.sharedState
3. global.redis.host

For example:

redis:
  install: false
global:
  redis:
    host: redis.example
    port: 6379
    auth:
      enabled: true
      secret: redis-secret
      key: redis-password
    actioncable:
      host: cable.redis.example
      port: 6379
      password:
        enabled: true
        secret: cable-secret
        key: cable-password
    cache:
      host: cache.redis.example
      port: 6379
      password:
        enabled: true
        secret: cache-secret
        key: cache-password
    kas:
      host: kas.redis.example
      port: 6379
      password:
        enabled: true
        secret: kas-secret
        key: kas-password
    queues:
      host: queues.redis.example
      port: 6379
      password:
        enabled: true
        secret: queues-secret
        key: queues-password
    rateLimiting:
      host: rateLimiting.redis.example
      port: 6379
      password:
        enabled: true
        secret: rateLimiting-secret
        key: rateLimiting-password
    repositoryCache:
      host: repositoryCache.redis.example
      port: 6379
      password:
        enabled: true
        secret: repositoryCache-secret
        key: repositoryCache-password
    sessions:
      host: sessions.redis.example
      port: 6379
      password:
        enabled: true
        secret: sessions-secret
        key: sessions-password
    sharedState:
      host: shared.redis.example
      port: 6379
      password:
        enabled: true
        secret: shared-secret
        key: shared-password
    traceChunks:
      host: traceChunks.redis.example
      port: 6379
      password:
        enabled: true
        secret: traceChunks-secret
        key: traceChunks-password
    workhorse:
      host: workhorse.redis.example
      port: 6379
      password:
        enabled: true
        secret: workhorse-secret
        key: workhorse-password

The following table describes the attributes for each dictionary of the Redis instances.

The primary Redis definition is required as there are additional persistence classes that have not been separated.

Each instance definition may also use Redis Sentinel support. Sentinel configurations are not shared and needs to be specified for each instance that uses Sentinels. Please refer to the Sentinel configuration for the attributes that are used to configure Sentinel servers.

Specify secure Redis scheme (SSL)

To connect to Redis with SSL:

1. Update your configuration to use the rediss (double s) scheme parameter.

2. In your configuration, set authClients to false:

   global:
     redis:
       scheme: rediss
   redis:
     tls:
       enabled: true
       authClients: false
   

   This configuration is required because Redis defaults to mutual TLS, which not all chart components support.

3. Follow Bitnami’s steps to enable TLS. Make sure the chart components trust the certificate authority used to create Redis certificates.
4. Optional. If you use a custom certificate authority, see the Custom Certificate Authorities global configuration.

Password-less Redis Servers

Some Redis services such as Google Cloud Memorystore do not make use of passwords and the associated AUTH command. The use and requirement for a password can be disabled via the following configuration setting:

global:
  redis:
    auth:
      enabled: false
    host: ${REDIS_PRIVATE_IP}
redis:
  enabled: false

Configure Registry settings

The global Registry settings are located under the global.registry key.

global:
  registry:
    bucket: registry
    certificate:
    httpSecret:
    notificationSecret:
    notifications: {}
    ## Settings used by other services, referencing registry:
    enabled: true
    host:
    api:
      protocol: http
      serviceName: registry
      port: 5000
    tokenIssuer: gitlab-issuer

For more details on bucket, certificate, httpSecret, and notificationSecret settings, see the documentation within the registry chart.

For details on enabled, host, api and tokenIssuer see documentation for command line options and webcervice

host is used to override autogenerated external registry hostname reference.

notifications

This setting is used to configure Registry notifications. It takes in a map (following upstream specification), but with an added feature of providing sensitive headers as Kubernetes secrets. For example, consider the following snippet where the Authorization header contains sensitive data while other headers contain regular data:

global:
  registry:
    notifications:
      events:
        includereferences: true
      endpoints:
        - name: CustomListener
          url: https://mycustomlistener.com
          timeout: 500mx
          # DEPRECATED: use `maxretries` instead https://gitlab.com/gitlab-org/container-registry/-/issues/1243.
          # When using `maxretries`, `threshold` is ignored: https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/configuration.md?ref_type=heads#endpoints
          threshold: 5
          maxretries: 5
          backoff: 1s
          headers:
            X-Random-Config: [plain direct]
            Authorization:
              secret: registry-authorization-header
              key: password

In this example, the header X-Random-Config is a regular header and its value can be provided in plaintext in the values.yaml file or via --set flag. However, the header Authorization is a sensitive one, so mounting it from a Kubernetes secret is preferred. For details regarding the structure of the secret, refer the secrets documentation

Configure Gitaly settings

The global Gitaly settings are located under the global.gitaly key.

global:
  gitaly:
    internal:
      names:
        - default
        - default2
    external:
      - name: node1
        hostname: node1.example.com
        port: 8075
    authToken:
      secret: gitaly-secret
      key: token
    tls:
      enabled: true
      secretName: gitlab-gitaly-tls

Gitaly hosts

Gitaly is a service that provides high-level RPC access to Git repositories, which handles all Git calls made by GitLab.

Administrators can chose to use Gitaly nodes in the following ways:

• Internal to the chart, as part of a StatefulSet via the Gitaly chart.
• External to the chart, as external pets.
• Mixed environment using both internal and external nodes.

See Repository Storage Paths documentation for details on managing which nodes will be used for new projects.

If gitaly.host is provided, gitaly.internal and gitaly.external properties will be ignored. See the deprecated Gitaly settings.

The Gitaly authentication token is expected to be identical for all Gitaly services at this time, internal or external. Ensure these are aligned. See issue #1992 for further details.

Internal

The internal key currently consists of only one key, names, which is a list of storage names to be managed by the chart. For each listed name, in logical order, one pod will be spawned, named ${releaseName}-gitaly-${ordinal}, where ordinal is the index within the names list. If dynamic provisioning is enabled, the PersistentVolumeClaim will match.

This list defaults to ['default'], which provides for 1 pod related to one storage path.

Manual scaling of this item is required, by adding or removing entries in gitaly.internal.names. When scaling down, any repository that has not been moved to another node will become unavailable. Since the Gitaly chart is a StatefulSet, dynamically provisioned disks will not be reclaimed. This means the data disks will persist, and the data on them can be accessed when the set is scaled up again by re-adding a node to the names list.

A sample configuration of multiple internal nodes can be found in the examples folder.

External

The external key provides a configuration for Gitaly nodes external to the cluster. Each item of this list has 3 keys:

• name: The name of the storage. An entry with name: default is required.
• hostname: The host of Gitaly services.
• port: (optional) The port number to reach the host on. Defaults to 8075.
• tlsEnabled: (optional) Override global.gitaly.tls.enabled for this particular entry.

We provide an advanced configuration guide for using an external Gitaly service. You can also find sample configuration of multiple external services in the examples folder.

You may use an external Praefect to provide highly available Gitaly services. Configuration of the two is interchangeable, as from the viewpoint of the clients, there is no difference.

Mixed

It is possible to use both internal and external Gitaly nodes, but be aware that:

• There must always be a node named default, which Internal provides by default.
• External nodes will be populated first, then Internal.

A sample configuration of mixed internal and external nodes can be found in the examples folder.

authToken

The authToken attribute for Gitaly has two sub keys:

• secret defines the name of the Kubernetes Secret to pull from.
• key defines the name of the key in the above secret that contains the authToken.

All Gitaly nodes must share the same authentication token.

Deprecated Gitaly settings

TLS settings

Configuring Gitaly to serve via TLS is detailed in the Gitaly chart’s documentation.

Configure Praefect settings

The global Praefect settings are located under the global.praefect key.

Praefect is disabled by default. When enabled with no extra settings, 3 Gitaly replicas will be created, and the Praefect database will need to be manually created on the default PostgreSQL instance.

Enable Praefect

To enable Praefect with default settings, set global.praefect.enabled=true.

See the Praefect documentation for details on how to operate a Gitaly cluster using Praefect.

Global settings for Praefect

global:
  praefect:
    enabled: false
    virtualStorages:
    - name: default
      gitalyReplicas: 3
      maxUnavailable: 1
    dbSecret: {}
    psql: {}

Configure MinIO settings

The GitLab global MinIO settings are located under the global.minio key. For more details on these settings, see the documentation within the MinIO chart.

global:
  minio:
    enabled: true
    credentials: {}

Configure appConfig settings

The Webservice, Sidekiq, and Gitaly charts share multiple settings, which are configured with the global.appConfig key.

global:
  appConfig:
    # cdnHost:
    contentSecurityPolicy:
      enabled: false
      report_only: true
      # directives: {}
    enableUsagePing: true
    enableSeatLink: true
    enableImpersonation: true
    applicationSettingsCacheSeconds: 60
    usernameChangingEnabled: true
    issueClosingPattern:
    defaultTheme:
    defaultColorMode:
    defaultSyntaxHighlightingTheme:
    defaultProjectsFeatures:
      issues: true
      mergeRequests: true
      wiki: true
      snippets: true
      builds: true
      containerRegistry: true
    webhookTimeout:
    gravatar:
      plainUrl:
      sslUrl:
    extra:
      googleAnalyticsId:
      matomoUrl:
      matomoSiteId:
      matomoDisableCookies:
      oneTrustId:
      googleTagManagerNonceId:
      bizible:
    object_store:
      enabled: false
      proxy_download: true
      storage_options: {}
      connection: {}
    lfs:
      enabled: true
      proxy_download: true
      bucket: git-lfs
      connection: {}
    artifacts:
      enabled: true
      proxy_download: true
      bucket: gitlab-artifacts
      connection: {}
    uploads:
      enabled: true
      proxy_download: true
      bucket: gitlab-uploads
      connection: {}
    packages:
      enabled: true
      proxy_download: true
      bucket: gitlab-packages
      connection: {}
    externalDiffs:
      enabled:
      when:
      proxy_download: true
      bucket: gitlab-mr-diffs
      connection: {}
    terraformState:
      enabled: false
      bucket: gitlab-terraform-state
      connection: {}
    ciSecureFiles:
      enabled: false
      bucket: gitlab-ci-secure-files
      connection: {}
    dependencyProxy:
      enabled: false
      bucket: gitlab-dependency-proxy
      connection: {}
    backups:
      bucket: gitlab-backups
    microsoft_graph_mailer:
      enabled: false
      user_id: "YOUR-USER-ID"
      tenant: "YOUR-TENANT-ID"
      client_id: "YOUR-CLIENT-ID"
      client_secret:
        secret:
        key: secret
      azure_ad_endpoint: "https://login.microsoftonline.com"
      graph_endpoint: "https://graph.microsoft.com"
    incomingEmail:
      enabled: false
      address: ""
      host: "imap.gmail.com"
      port: 993
      ssl: true
      startTls: false
      user: ""
      password:
        secret:
        key: password
      mailbox: inbox
      idleTimeout: 60
      inboxMethod: "imap"
      clientSecret:
        key: secret
      pollInterval: 60
      deliveryMethod: webhook
      authToken: {}

    serviceDeskEmail:
      enabled: false
      address: ""
      host: "imap.gmail.com"
      port: 993
      ssl: true
      startTls: false
      user: ""
      password:
        secret:
        key: password
      mailbox: inbox
      idleTimeout: 60
      inboxMethod: "imap"
      clientSecret:
        key: secret
      pollInterval: 60
      deliveryMethod: webhook
      authToken: {}

    cron_jobs: {}
    sentry:
      enabled: false
      dsn:
      clientside_dsn:
      environment:
    gitlab_docs:
      enabled: false
      host: ""
    smartcard:
      enabled: false
      CASecret:
      clientCertificateRequiredHost:
    sidekiq:
      routingRules: []

General application settings

The appConfig settings that can be used to tweak the general properties of the Rails application are described below:

Content Security Policy

Setting a Content Security Policy (CSP) can help thwart JavaScript cross-site scripting (XSS) attacks. See GitLab documentation for configuration details. Content Security Policy Documentation

GitLab automatically provides secure default values for the CSP.

global:
  appConfig:
    contentSecurityPolicy:
      enabled: true
      report_only: false

To add a custom CSP:

global:
  appConfig:
    contentSecurityPolicy:
      enabled: true
      report_only: false
      directives:
        default_src: "'self'"
        script_src: "'self' 'unsafe-inline' 'unsafe-eval' https://www.recaptcha.net https://apis.google.com"
        frame_ancestors: "'self'"
        frame_src: "'self' https://www.recaptcha.net/ https://content.googleapis.com https://content-compute.googleapis.com https://content-cloudbilling.googleapis.com https://content-cloudresourcemanager.googleapis.com"
        img_src: "* data: blob:"
        style_src: "'self' 'unsafe-inline'"

Improperly configuring the CSP rules could prevent GitLab from working properly. Before rolling out a policy, you may also want to change report_only to true to test the configuration.

defaultProjectsFeatures

Flags to decide if new projects should be created with the respective features by default. All flags default to true.

defaultProjectsFeatures:
  issues: true
  mergeRequests: true
  wiki: true
  snippets: true
  builds: true
  containerRegistry: true

Gravatar/Libravatar settings

By default, the charts work with Gravatar avatar service available at gravatar.com. However, a custom Libravatar service can also be used if needed:

Hooking Analytics services to the GitLab instance

Settings to configure Analytics services like Google Analytics and Matomo are defined under the extra key below appConfig:

Consolidated object storage

In addition to the following section that describes how to configure individual settings for object storage, we’ve added a consolidated object storage configuration to ease the use of shared configuration for these items. Making use of object_store, you can configure a connection once, and it will be used for any and all object storage backed features that are not individually configured with a connection property.

  enabled: true
  proxy_download: true
  storage_options:
  connection:
    secret:
    key:

The property structure is shared, and all properties here can be overridden by the individual items below. The connection property structure is identical.

Notice: The bucket, enabled, and proxy_download properties are the only properties that must be configured on a per-item level (global.appConfig.artifacts.bucket, …) if you wish to deviate from the default values.

When using the AWS provider for the connection (which is any S3 compatible provider such as the included MinIO), GitLab Workhorse can offload all storage related uploads. This will automatically be enabled for you, when using this consolidated configuration.

Specify buckets

Each object type should be stored in different buckets. By default, GitLab uses these bucket names for each type:

You can use these defaults or configure the bucket names:

--set global.appConfig.artifacts.bucket=<BUCKET NAME> \
--set global.appConfig.lfs.bucket=<BUCKET NAME> \
--set global.appConfig.packages.bucket=<BUCKET NAME> \
--set global.appConfig.uploads.bucket=<BUCKET NAME> \
--set global.appConfig.externalDiffs.bucket=<BUCKET NAME> \
--set global.appConfig.terraformState.bucket=<BUCKET NAME> \
--set global.appConfig.ciSecureFiles.bucket=<BUCKET NAME> \
--set global.appConfig.dependencyProxy.bucket=<BUCKET NAME>

storage_options

The storage_options are used to configure S3 Server Side Encryption.

Setting a default encryption on an S3 bucket is the easiest way to enable encryption, but you may want to set a bucket policy to ensure only encrypted objects are uploaded. To do this, you must configure GitLab to send the proper encryption headers in the storage_options configuration section:

Example:

  enabled: true
  proxy_download: true
  connection:
    secret: gitlab-rails-storage
    key: connection
  storage_options:
    server_side_encryption: aws:kms
    server_side_encryption_kms_key_id: arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

LFS, Artifacts, Uploads, Packages, External MR diffs, and Dependency Proxy

Details on these settings are below. Documentation is not repeated individually, as they are structurally identical aside from the default value of the bucket property.

  enabled: true
  proxy_download: true
  bucket:
  connection:
    secret:
    key:

connection

The connection property has been transitioned to a Kubernetes Secret. The contents of this secret should be a YAML formatted file. Defaults to {} and will be ignored if global.minio.enabled is true.

This property has two sub-keys: secret and key.

• secret is the name of a Kubernetes Secret. This value is required to use external object storage.
• key is the name of the key in the secret which houses the YAML block. Defaults to connection.

Valid configuration keys can be found in the GitLab Job Artifacts Administration documentation. This matches to Fog, and is different between provider modules.

Examples for AWS and Google providers can be found in examples/objectstorage.

• rails.s3.yaml
• rails.gcs.yaml
• rails.azurerm.yaml

Once a YAML file containing the contents of the connection has been created, use this file to create the secret in Kubernetes.

kubectl create secret generic gitlab-rails-storage \
    --from-file=connection=rails.yaml

when (only for External MR Diffs)

externalDiffs setting has an additional key when to conditionally store specific diffs on object storage. This setting is left empty by default in the charts, for a default value to be assigned by the Rails code.

cdn (only for CI Artifacts)

artifacts setting has an additional key cdn to configure Google CDN in front of a Google Cloud Storage bucket.

Incoming email settings

The incoming email settings are explained in the command line options page.

KAS settings

Custom secret

One can optionally customize the KAS secret name as well as key, either by using Helm’s --set variable option:

--set global.appConfig.gitlab_kas.secret=custom-secret-name \
--set global.appConfig.gitlab_kas.key=custom-secret-key \

or by configuring your values.yaml:

global:
  appConfig:
    gitlab_kas:
      secret: "custom-secret-name"
      key: "custom-secret-key"

If you’d like to customize the secret value, refer to the secrets documentation.

Custom URLs

The URLs used for KAS by the GitLab backend can be customized using Helm’s --set variable option:

--set global.appConfig.gitlab_kas.externalUrl="wss://custom-kas-url.example.com" \
--set global.appConfig.gitlab_kas.internalUrl="grpc://custom-internal-url" \

or by configuring your values.yaml:

global:
  appConfig:
    gitlab_kas:
      externalUrl: "wss://custom-kas-url.example.com"
      internalUrl: "grpc://custom-internal-url"

External KAS

The GitLab backend can be made aware of an external KAS server (i.e. not managed by the chart) by explicitly enabling it and configuring the required URLs. You can do so using Helm’s --set variable option:

--set global.appConfig.gitlab_kas.enabled=true \
--set global.appConfig.gitlab_kas.externalUrl="wss://custom-kas-url.example.com" \
--set global.appConfig.gitlab_kas.internalUrl="grpc://custom-internal-url" \

or by configuring your values.yaml:

global:
  appConfig:
    gitlab_kas:
      enabled: true
      externalUrl: "wss://custom-kas-url.example.com"
      internalUrl: "grpc://custom-internal-url"

TLS settings

KAS supports TLS communication between its kas pods and other GitLab chart components.

Prerequisites:

• Use GitLab 15.5.1 or later. You can set your GitLab version with global.gitlabVersion: <version>. If you need to force an image update after an initial deployment, also set global.image.pullPolicy: Always.
• Create the certificate authority and certificates that your kas pods will trust.

To configure kas to use the certificates you created, set the following values.

For example, you could use the following in your values.yaml file to deploy your chart:

.internal-ca: &internal-ca gitlab-internal-tls-ca # The secret name you used to share your TLS CA.
.internal-tls: &internal-tls gitlab-internal-tls # The secret name you used to share your TLS certificate.

global:
  certificates:
    customCAs:
    - secret: *internal-ca
  hosts:
    domain: gitlab.example.com # Your gitlab domain
  kas:
    tls:
      enabled: true
      secretName: *internal-tls
      caSecretName: *internal-ca

Suggested Reviewers settings

One can optionally customize the Suggested Reviewers secret name as well as key, either by using Helm’s --set variable option:

--set global.appConfig.suggested_reviewers.secret=custom-secret-name \
--set global.appConfig.suggested_reviewers.key=custom-secret-key \

or by configuring your values.yaml:

global:
  appConfig:
    suggested_reviewers:
      secret: "custom-secret-name"
      key: "custom-secret-key"

If you’d like to customize the secret value, refer to the secrets documentation.

LDAP

The ldap.servers setting allows for the configuration of LDAP user authentication. It is presented as a map, which will be translated into the appropriate LDAP servers configuration in gitlab.yml, as with an installation from source.

Configuring passwords can be done by supplying a secret which holds the password. This password will then be injected into the GitLab configuration at runtime.

An example configuration snippet:

ldap:
  preventSignin: false
  servers:
    # 'main' is the GitLab 'provider ID' of this LDAP server
    main:
      label: 'LDAP'
      host: '_your_ldap_server'
      port: 636
      uid: 'sAMAccountName'
      bind_dn: 'cn=administrator,cn=Users,dc=domain,dc=net'
      base: 'dc=domain,dc=net'
      password:
        secret: my-ldap-password-secret
        key: the-key-containing-the-password

Example --set configuration items, when using the global chart:

--set global.appConfig.ldap.servers.main.label='LDAP' \
--set global.appConfig.ldap.servers.main.host='your_ldap_server' \
--set global.appConfig.ldap.servers.main.port='636' \
--set global.appConfig.ldap.servers.main.uid='sAMAccountName' \
--set global.appConfig.ldap.servers.main.bind_dn='cn=administrator\,cn=Users\,dc=domain\,dc=net' \
--set global.appConfig.ldap.servers.main.base='dc=domain\,dc=net' \
--set global.appConfig.ldap.servers.main.password.secret='my-ldap-password-secret' \
--set global.appConfig.ldap.servers.main.password.key='the-key-containing-the-password'

Disable LDAP web sign in

It can be useful to prevent using LDAP credentials through the web UI when an alternative such as SAML is preferred. This allows LDAP to be used for group sync, while also allowing your SAML identity provider to handle additional checks like custom 2FA.

When LDAP web sign in is disabled, users will not see a LDAP tab on the sign in page. This does not disable using LDAP credentials for Git access.

To disable the use of LDAP for web sign-in, set global.appConfig.ldap.preventSignin: true.

Using a custom CA or self signed LDAP certificates

If the LDAP server uses a custom CA or self-signed certificate, you must:

1. Ensure that the custom CA/Self-Signed certificate is created as a Secret or ConfigMap in the cluster/namespace:

   # Secret
   kubectl -n gitlab create secret generic my-custom-ca-secret --from-file=unique_name.crt=my-custom-ca.pem
   
   # ConfigMap
   kubectl -n gitlab create configmap my-custom-ca-configmap --from-file=unique_name.crt=my-custom-ca.pem
   

2. Then, specify:

   # Configure a custom CA from a Secret
   --set global.certificates.customCAs[0].secret=my-custom-ca-secret
   
   # Or from a ConfigMap
   --set global.certificates.customCAs[0].configMap=my-custom-ca-configmap
   
   # Configure the LDAP integration to trust the custom CA
   --set global.appConfig.ldap.servers.main.ca_file=/etc/ssl/certs/unique_name.pem
   

This ensures that the CA certificate is mounted in the relevant pods at /etc/ssl/certs/unique_name.pem and specifies its use in the LDAP configuration.

See Custom Certificate Authorities for more info.

DuoAuth

Use these settings to enable two-factor authentication (2FA) with GitLab Duo.

global:
  appConfig:
    duoAuth:
      enabled:
      hostname:
      integrationKey:
      secretKey:
      #  secret:
      #  key:

Configure the GitLab Duo secret key

To configure GitLab Duo auth integration in the GitLab Helm chart you must provide a secret in the global.appConfig.duoAuth.secretKey.secret setting containing GitLab Duo auth secret_key value.

To create a Kubernetes secret object to store your GitLab Duo account secretKey, from the command line, run:

kubectl create secret generic <secret_object_name> --from-literal=secretKey=<duo_secret_key_value>

OmniAuth

GitLab can leverage OmniAuth to allow users to sign in using Twitter, GitHub, Google, and other popular services. Expanded documentation can be found in the OmniAuth documentation for GitLab.

omniauth:
  enabled: false
  autoSignInWithProvider:
  syncProfileFromProvider: []
  syncProfileAttributes: ['email']
  allowSingleSignOn: ['saml']
  blockAutoCreatedUsers: true
  autoLinkLdapUser: false
  autoLinkSamlUser: false
  autoLinkUser: ['saml']
  externalProviders: []
  allowBypassTwoFactor: []
  providers: []
  # - secret: gitlab-google-oauth2
  #   key: provider
  # - name: group_saml

providers

providers is presented as an array of maps that are used to populate gitlab.yml as when installed from source. See GitLab documentation for the available selection of Supported Providers. Defaults to [].

This property has two sub-keys: secret and key:

• secret: (required) The name of a Kubernetes Secret containing the provider block.
• key: (optional) The name of the key in the Secret containing the provider block. Defaults to provider

Alternatively, if the provider has no other configuration than its name, you may use a second form with only a ‘name’ attribute, and optionally a label or icon attribute. The eligible providers are:

• group_saml
• kerberos

The Secret for these entries contains YAML or JSON formatted blocks, as described in OmniAuth Providers. To create this secret, follow the appropriate instructions for retrieval of these items, and create a YAML or JSON file.

Example of configuration of Google OAuth2:

name: google_oauth2
label: Google
app_id: 'APP ID'
app_secret: 'APP SECRET'
args:
  access_type: offline
  approval_prompt: ''

SAML configuration example:

name: saml
label: 'SAML'
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: 'xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx'
  idp_sso_target_url: 'https://SAML_IDP/app/xxxxxxxxx/xxxxxxxxx/sso/saml'
  issuer: 'https://gitlab.example.com'
  name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'

Microsoft Azure OAuth 2.0 OmniAuth provider configuration example:

name: azure_activedirectory_v2
label: Azure
args:
  client_id: '<CLIENT_ID>'
  client_secret: '<CLIENT_SECRET>'
  tenant_id: '<TENANT_ID>'

This content can be saved as provider.yaml, and then a secret created from it:

kubectl create secret generic -n NAMESPACE SECRET_NAME --from-file=provider=provider.yaml

Once created, the providers are enabled by providing the maps in configuration, as shown below:

omniauth:
  providers:
    - secret: gitlab-google-oauth2
    - secret: azure_activedirectory_v2
    - secret: gitlab-azure-oauth2
    - secret: gitlab-cas3

Group SAML configuration example:

omniauth:
  providers:
    - name: group_saml

Example configuration --set items, when using the global chart:

--set global.appConfig.omniauth.providers[0].secret=gitlab-google-oauth2 \

Due to the complexity of using --set arguments, a user may wish to use a YAML snippet, passed to helm with -f omniauth.yaml.

Cron jobs related settings

Sidekiq includes maintenance jobs that can be configured to run on a periodic basis using cron style schedules. A few examples are included below. See the cron_jobs and ee_cron_jobs sections in the sample gitlab.yml for more job examples.

These settings are shared between Sidekiq, Webservice (for showing tooltips in UI) and Toolbox (for debugging purposes) pods.

global:
  appConfig:
    cron_jobs:
      stuck_ci_jobs_worker:
        cron: "0 * * * *"
      pipeline_schedule_worker:
        cron: "3-59/10 * * * *"
      expire_build_artifacts_worker:
        cron: "*/7 * * * *"

Sentry settings

Use these settings to enable GitLab error reporting with Sentry.

global:
  appConfig:
    sentry:
      enabled:
      dsn:
      clientside_dsn:
      environment:

gitlab_docs settings

Use these settings to enable gitlab_docs.

global:
  appConfig:
    gitlab_docs:
      enabled:
      host:

Smartcard Authentication settings

global:
  appConfig:
    smartcard:
      enabled: false
      CASecret:
      clientCertificateRequiredHost:
      sanExtensions: false
      requiredForGitAccess: false

Sidekiq routing rules settings

GitLab supports routing a job from a worker to a desired queue before it is scheduled. Sidekiq clients match a job against a configured list of routing rules. Rules are evaluated from first to last, and as soon as a match for a given worker is found, the processing for that worker is stopped (first match wins). If the worker doesn’t match any rule, it falls back the queue name generated from the worker name.

By default, the routing rules are not configured (or denoted with an empty array), all the jobs are routed to the queue generated from the worker name.

The routing rules list is an ordered array of tuples of query and corresponding queue:

• The query is following the worker matching query syntax.
• The <queue_name> must match a valid Sidekiq queue name sidekiq.pods[].queues defined under sidekiq.pods. If the queue name is nil, or an empty string, the worker is routed to the queue generated by the name of the worker instead. See Full example of Sidekiq configuration as a reference.

The query supports wildcard matching *, which matches all workers. As a result, the wildcard query must stay at the end of the list or the later rules are ignored:

global:
  appConfig:
    sidekiq:
      routingRules:
      - ["resource_boundary=cpu", "cpu-boundary"]
      - ["feature_category=pages", null]
      - ["feature_category=search", "search"]
      - ["feature_category=memory|resource_boundary=memory", "memory-bound"]
      - ["*", "default"]

Configure Rails settings

A large portion of the GitLab suite is based upon Rails. As such, many containers within this project operate with this stack. These settings apply to all of those containers, and provide an easy access method to setting them globally versus individually.

global:
  rails:
    bootsnap:
      enabled: true

Configure Workhorse settings

Several components of the GitLab suite speak to the APIs via GitLab Workhorse. This is currently a part of the Webservice chart. These settings are consumed by all charts that need to contact GitLab Workhorse, providing an easy access to set them globally vs individually.

global:
  workhorse:
    serviceName: webservice-default
    host: api.example.com
    port: 8181

Bootsnap Cache

Our Rails codebase makes use of Shopify’s Bootsnap Gem. Settings here are used to configure that behavior.

bootsnap.enabled controls the activation of this feature. It defaults to true.

Testing showed that enabling Bootsnap resulted in overall application performance boost. When a pre-compiled cache is available, some application containers see gains in excess of 33%. At this time, GitLab does not ship this pre-compiled cache with their containers, resulting in a gain of “only” 14%. There is a cost to this gain without the pre-compiled cache present, resulting in an intense spike of small IO at initial startup of each Pod. Due to this, we’ve exposed a method of disabling the use of Bootsnap in environments where this would be an issue.

When possible, we recommend leaving this enabled.

Configure GitLab Shell

There are several items for the global configuration of GitLab Shell chart.

global:
  shell:
    port:
    authToken: {}
    hostKeys: {}
    tcp:
      proxyProtocol: false

Port

You can control the port used by the Ingress to pass SSH traffic, as well as the port used in SSH URLs provided from GitLab via global.shell.port. This is reflected in the port on which the service listens, as well as the SSH clone URLs provided in project UI.

global:
  shell:
    port: 32022

You can combine global.shell.port and nginx-ingress.controller.service.type=NodePort to set a NodePort for the NGINX controller Service object. Note that if nginx-ingress.controller.service.nodePorts.gitlab-shell is set, it will override global.shell.port when setting the NodePort for NGINX.

global:
  shell:
    port: 32022

nginx-ingress:
  controller:
    service:
      type: NodePort

TCP proxy protocol

You can enable handling proxy protocol on the SSH Ingress to properly handle a connection from an upstream proxy that adds the proxy protocol header. By doing so, this will prevent SSH from receiving the additional headers and not break SSH.

One common environment where one needs to enable handling of proxy protocol is when using AWS with an ELB handling the inbound connections to the cluster. You can consult the AWS layer 4 loadbalancer example to properly set it up.

global:
  shell:
    tcp:
      proxyProtocol: true # default false

Configure GitLab Pages

The global GitLab Pages settings that are used by other charts are documented under the global.pages key.

global:
  pages:
    enabled:
    accessControl:
    path:
    host:
    port:
    https:
    externalHttp:
    externalHttps:
    artifactsServer:
    objectStore:
      enabled:
      bucket:
      proxy_download: true
      connection: {}
        secret:
        key:
    localStore:
      enabled: false
      path:
    apiSecret: {}
      secret:
      key:
    namespaceInPath: false

Configure Webservice

The global Webservice settings (that are used by other charts also) are located under the global.webservice key.

global:
  webservice:
    workerTimeout: 60

workerTimeout

Configure the request timeout (in seconds) after which a Webservice worker process is killed by the Webservice master process. The default value is 60 seconds.

The global.webservice.workerTimeout setting does not affect the maximum request duration. To set the maximum request duration, set the following environment variables:

gitlab:
  webservice:
    workerTimeout: 60
    extraEnv:
      GITLAB_RAILS_RACK_TIMEOUT: "60"
      GITLAB_RAILS_WAIT_TIMEOUT: "90"

Custom Certificate Authorities

Some users may need to add custom certificate authorities, such as when using internally issued SSL certificates for TLS services. To provide this functionality, we provide a mechanism for injecting these custom root certificate authorities into the application through Secrets or ConfigMaps.

To create a Secret or ConfigMap:

# Create a Secret from a certificate file
kubectl create secret generic secret-custom-ca --from-file=unique_name.crt=/path/to/cert

# Create a ConfigMap from a certificate file
kubectl create configmap cm-custom-ca --from-file=unique_name.crt=/path/to/cert

To configure a Secret or ConfigMap, or both, specify them in globals:

global:
  certificates:
    customCAs:
      - secret: secret-custom-CAs           # Mount all keys of a Secret
      - secret: secret-custom-CAs           # Mount only the specified keys of a Secret
        keys:
          - unique_name.crt
      - configMap: cm-custom-CAs            # Mount all keys of a ConfigMap
      - configMap: cm-custom-CAs            # Mount only the specified keys of a ConfigMap
        keys:
          - unique_name_1.crt
          - unique_name_2.crt

You can provide any number of Secrets or ConfigMaps, each containing any number of keys that hold PEM-encoded CA certificates. These are configured as entries under global.certificates.customCAs. All keys are mounted unless keys: is provided with a list of specific keys to be mounted. All mounted keys across all Secrets and ConfigMaps must be unique. The Secrets and ConfigMaps can be named in any fashion, but they must not contain key names that collide.

Application Resource

GitLab can optionally include an Application resource, which can be created to identify the GitLab application within the cluster. Requires the Application CRD, version v1beta1, to already be deployed to the cluster.

To enable, set global.application.create to true:

global:
  application:
    create: true

Some environments, such as Google GKE Marketplace, do not allow the creation of ClusterRole resources. Set the following values to disable ClusterRole components in the Application Custom Resource Definition as well as the relevant charts packaged with Cloud Native GitLab.

global:
  application:
    allowClusterRoles: false
nginx:
  controller:
    scope:
      enabled: true
gitlab-runner:
  rbac:
    clusterWideAccess: false
certmanager:
  install: false

GitLab base image

GitLab Helm chart uses a common GitLab base image for various initialization tasks. This image support UBI builds and shares layers with other images.

Service Accounts

GitLab Helm charts allow for the pods to run using custom Service Accounts. This is configured with the following settings in global.serviceAccount:

global:
  serviceAccount:
    enabled: false
    create: true
    annotations: {}
    automountServiceAccountToken: false
    ## Name to be used for serviceAccount, otherwise defaults to chart fullname
    # name:

• Setting global.serviceAccount.enabled controls reference to a ServiceAccount for each component via spec.serviceAccountName.
• Setting global.serviceAccount.create controls ServiceAccount object creation via Helm.
• Setting global.serviceAccount.name controls the ServiceAccount object name and the name referenced by each component.
• Setting global.serviceAccount.automountServiceAccountToken controls if the default ServiceAccount access token should be mounted in pods. You should not enable this unless it is required by certain sidecars to work properly (for example, Istio).

Annotations

Custom annotations can be applied to Deployment, Service, and Ingress objects.

global:
  deployment:
    annotations:
      environment: production

  service:
    annotations:
      environment: production

  ingress:
    annotations:
      environment: production

Node Selector

Custom nodeSelectors can be applied to all components globally. Any global defaults can also be overridden on each subchart individually.

global:
  nodeSelector:
    disktype: ssd

Labels

Common Labels

Labels can be applied to nearly all objects that are created by various objects by using the configuration common.labels. This can be applied under the global key, or under a specific charts’ configuration. Example:

global:
  common:
    labels:
      environment: production
gitlab:
  gitlab-shell:
    common:
      labels:
        foo: bar

With the above example configuration, nearly all components deployed by the Helm chart will be provided the label set environment: production. All components of the GitLab Shell chart will receive the label set foo: bar. Some charts allow for additional nesting. For example, the Sidekiq and Webservices charts allow for additional deployments depending on your configuration needs:

gitlab:
  sidekiq:
    pods:
      - name: pod-0
        common:
          labels:
            baz: bat

In the above example, all components associated with the pod-0 Sidekiq deployment will also recieve the label set baz: bat. Refer to the Sidekiq and Webservice charts for additional details.

Some charts that we depend on are excluded from this label configuration. Only the GitLab component sub-charts will receive these extra labels.

Pod

Custom labels can be applied to various Deployments and Jobs. These labels are supplementary to existing or preconfigured labels constructed by this Helm chart. These supplementary labels will not be utilized for matchSelectors.

global:
  pod:
    labels:
      environment: production

Service

Custom labels can be applied to services. These labels are supplementary to existing or preconfigured labels constructed by this Helm chart.

global:
  service:
    labels:
      environment: production

Tracing

GitLab Helm charts support tracing, and you can configure it with:

global:
  tracing:
    connection:
      string: 'opentracing://jaeger?http_endpoint=http%3A%2F%2Fjaeger.example.com%3A14268%2Fapi%2Ftraces&sampler=const&sampler_param=1'
    urlTemplate: 'http://jaeger-ui.example.com/search?service={{ service }}&tags=%7B"correlation_id"%3A"{{ correlation_id }}"%7D'

• global.tracing.connection.string is used to configure where tracing spans would be sent. You can read more about that in GitLab tracing documentation
• global.tracing.urlTemplate is used as a template for tracing info URL rendering in GitLab performance bar.

extraEnv

extraEnv allows you to expose additional environment variables in all containers in the pods that are deployed via GitLab charts (charts/gitlab/charts). Extra environment variables set at the global level will be merged into those provided at the chart level, with precedence given to those provided at the chart level.

Below is an example use of extraEnv:

global:
  extraEnv:
    SOME_KEY: some_value
    SOME_OTHER_KEY: some_other_value

extraEnvFrom

extraEnvFrom allows to expose additional environment variables from other data sources in all containers in the pods. Extra environment variables can be set up at global level (global.extraEnvFrom) and on a sub-chart level (<subchart_name>.extraEnvFrom).

The Sidekiq and Webservice charts support additional local overrides. See their documentation for more details.

Below is an example use of extraEnvFrom:

global:
  extraEnvFrom:
    MY_NODE_NAME:
      fieldRef:
        fieldPath: spec.nodeName
    MY_CPU_REQUEST:
      resourceFieldRef:
        containerName: test-container
        resource: requests.cpu
gitlab:
  kas:
    extraEnvFrom:
      CONFIG_STRING:
        configMapKeyRef:
          name: useful-config
          key: some-string
          # optional: boolean

Configure OAuth settings

OAuth integration is configured out-of-the box for services which support it. The services specified in global.oauth are automatically registered as OAuth client applications in GitLab during deployment. By default this list includes GitLab Pages, if access control is enabled.

global:
  oauth:
    gitlab-pages: {}
    # secret
    # appid
    # appsecret
    # redirectUri
    # authScope

Check the secrets documentation for more details on the secret.

Kerberos

To configure the Kerberos integration in the GitLab Helm chart, you must provide a secret in the global.appConfig.kerberos.keytab.secret setting containing a Kerberos keytab with a service principal for your GitLab host. Your Kerberos administrators can help with creating a keytab file if you don’t have one.

You can create a secret using the following snippet (assuming that you are installing the chart in the gitlab namespace and gitlab.keytab is the keytab file containing the service principal):

kubectl create secret generic gitlab-kerberos-keytab --namespace=gitlab --from-file=keytab=./gitlab.keytab

Kerberos integration for Git is enabled by setting global.appConfig.kerberos.enabled=true. This will also add the kerberos provider to the list of enabled OmniAuth providers for ticket-based authentication in the browser.

If left as false the Helm chart will still mount the keytab in the toolbox, Sidekiq, and webservice Pods, which can be used with manually configured OmniAuth settings for Kerberos.

You can provide a Kerberos client configuration in global.appConfig.kerberos.krb5Config.

global:
  appConfig:
    kerberos:
      enabled: true
      keytab:
        secret: gitlab-kerberos-keytab
        key: keytab
      servicePrincipalName: ""
      krb5Config: |
        [libdefaults]
            default_realm = EXAMPLE.COM
      dedicatedPort:
        enabled: false
        port: 8443
        https: true
      simpleLdapLinkingAllowedRealms:
        - example.com

Check the Kerberos documentation for more details.

Dedicated port for Kerberos

GitLab supports the use of a dedicated port for Kerberos negotiation when using the HTTP protocol for Git operations to workaround a limitation in Git falling back to Basic Authentication when presented with the negotiate headers in the authentication exchange.

Use of the dedicated port is currently required when using GitLab CI/CD - as the GitLab Runner helper relies on in-URL credentials to clone from GitLab.

This can be enabled with the global.appConfig.kerberos.dedicatedPort settings:

global:
  appConfig:
    kerberos:
      [...]
      dedicatedPort:
        enabled: true
        port: 8443
        https: true

This enables an additional clone URL in the GitLab UI that is dedicated for Kerberos negotiation. The https: true setting is for URL generation only, and doesn’t expose any additional TLS configuration. TLS is terminated and configured in the Ingress for GitLab.

LDAP custom allowed realms

The global.appConfig.kerberos.simpleLdapLinkingAllowedRealms can be used to specify a set of domains used to link LDAP and Kerberos identities together when a user’s LDAP DN does not match the user’s Kerberos realm. See the Custom allowed realms section in the Kerberos integration documentation for additional details.

Outgoing email

Outgoing email configuration is available via global.smtp.*, global.appConfig.microsoft_graph_mailer.* and global.email.*.

global:
  email:
    display_name: 'GitLab'
    from: 'gitlab@example.com'
    reply_to: 'noreply@example.com'
  smtp:
    enabled: true
    address: 'smtp.example.com'
    tls: true
    authentication: 'plain'
    user_name: 'example'
    password:
      secret: 'smtp-password'
      key: 'password'
  appConfig:
    microsoft_graph_mailer:
      enabled: false
      user_id: "YOUR-USER-ID"
      tenant: "YOUR-TENANT-ID"
      client_id: "YOUR-CLIENT-ID"
      client_secret:
        secret:
        key: secret
      azure_ad_endpoint: "https://login.microsoftonline.com"
      graph_endpoint: "https://graph.microsoft.com"

More information on the available configuration options is available in the outgoing email documentation.

More detailed examples can be found in the Linux package SMTP settings documentation.

Platform

The platform key is reserved for specific features targeting a specific platform like GKE or EKS.

Affinity

Affinity configuration is available via global.antiAffinity and global.affinity. Affinity allows you to constrain which nodes your pod is eligible to be scheduled on, based on node labels or labels of pods that are already running on a node. This allow spread pods across the cluster or select specific nodes, ensuring more resilience in case of a failing node.

global:
  antiAffinity: soft
  affinity:
    podAntiAffinity:
      topologyKey: "kubernetes.io/hostname"

• global.antiAffinity can take two values:
  • soft: Define a preferredDuringSchedulingIgnoredDuringExecution anti-affinity where the Kubernetes scheduler will try to enforce the rule but will not guarantee the result.
  • hard: Defined a requiredDuringSchedulingIgnoredDuringExecution anti-affinity where the rule must be met for a pod to be scheduled onto a node.
• global.affinity.podAntiAffinity.topologyKey define a node attribute used two divide them into logical zone. Most common topologyKey values are :
  • kubernetes.io/hostname
  • topology.kubernetes.io/zone
  • topology.kubernetes.io/region

Kubernetes references on Inter-pod affinity and anti-affinity

Pod Priority and Preemption

Pod priorities can be configured either via global.priorityClassName or per sub-chart via priorityClassName. Setting pod priority allows you to tell the scheduler to evict lower priority pods to make scheduling of pendings pods possible.

global:
  priorityClassName: system-cluster-critical

Log rotation

By default, the GitLab Helm chart does not rotate logs. This can cause ephemeral storage issues for containers that run for a long time.

To enable log rotation, set the GITLAB_LOGGER_TRUNCATE_LOGS environment variable to true. For more information, see GitLab Logger’s documentation. In particular, see information on:

• GITLAB_LOGGER_TRUNCATE_INTERVAL.
• GITLAB_LOGGER_MAX_FILESIZE.

Jobs

Originally, jobs in GitLab were suffixed with the Helm .Release.Revision which was not ideal because it would always cause an update of the job when running helm upgrade --install, even if nothing has changed. And it also prevented the proper work with workflows that are based on helm template, for example when using ArgoCD. The decision to use the .Release.Revision in the name was based on the preconditions that the job might only be executed once and that helm uninstall wouldn’t delete jobs, which are (now) wrong.

With GitLab Helm chart 7.9 and later, job names by default are suffixed with a hash that is based on the chart’s app version and the chart’s values, which also might contain the global.gitlabVersion. This approach ensures job names remain stable across multiple helm template and helm upgrade --install executions (if nothing changed), and it’s even possible to modify values of immutable fields of the job without errors during deployments (the jobs are just replaced with new ones due to the new names).

It is possible to override the hash that gets generated by default with a custom suffix by setting global.job.nameSuffixOverride. The field supports templating, so it is possible to reproduce the old behavior of using the .Release.Revision as a name suffix:

global:
  job:
    nameSuffixOverride: '{{ .Release.Revision }}'

If you intentionally always want to trigger a change, for example, because you are working with floating tags such as latest for all your versions, you can override the hash that gets generated by default with a dynamic value such as a timestamp:

global:
  job:
    nameSuffixOverride: '{{ dateInZone "2006-01-02-15-04-05" (now) "UTC" }}'

Alternatively, you can use it with helm in the command line:

helm <command> <options> --set global.job.nameSuffixOverride=$(date +%Y-%m-%d-%H-%M-%S)

Traefik

The Traefik settings can be configured via globals.traefik.

global:
  traefik:
    apiVersion: ""