Using the GitLab-Gitaly chart

The gitaly sub-chart provides a configurable deployment of Gitaly Servers.


This chart depends on access to the Workhorse service, either as part of the complete GitLab chart or provided as an external service reachable from the Kubernetes cluster this chart is deployed onto.

Design Choices

The Gitaly container used in this chart also contains the GitLab Shell codebase in order to perform the actions on the Git repositories that have not yet been ported into Gitaly. The Gitaly container includes a copy of the GitLab Shell container within it, and as a result we also need to configure GitLab Shell within this chart.


The gitaly chart is configured in two parts: external services, and chart settings.

Gitaly is by default deployed as a component when deploying the GitLab chart. If deploying Gitaly separately, global.gitaly.enabled needs to be set to false and additional configuration will need to be performed as described in the external Gitaly documentation.

Installation command line options

The table below contains all the possible charts configurations that can be supplied to the helm install command using the --set flags.

Parameter Default Description
annotations   Pod annotations
common.labels {} Supplemental labels that are applied to all objects created by this chart.
podLabels   Supplemental Pod labels. Will not be used for selectors.
external[].hostname - "" hostname of external node
external[].name - "" name of external node storage
external[].port - "" port of external node
extraContainers   List of extra containers to include
extraInitContainers   List of extra init containers to include
extraVolumeMounts   List of extra volumes mounts to do
extraVolumes   List of extra volumes to create
extraEnv   List of extra environment variables to expose
extraEnvFrom   List of extra environment variables from other data sources to expose
gitaly.serviceName   The name of the generated Gitaly service. Overrides global.gitaly.serviceName, and defaults to <RELEASE-NAME>-gitaly
image.pullPolicy Always Gitaly image pull policy
image.pullSecrets   Secrets for the image repository
image.repository Gitaly image repository
image.tag master Gitaly image tag
init.image.repository   initContainer image
init.image.tag   initContainer image tag
internal.names[] - default Ordered names of StatefulSet storages
serviceLabels {} Supplemental service labels
service.externalPort 8075 Gitaly service exposed port
service.internalPort 8075 Gitaly internal port gitaly The name of the Service port that Gitaly is behind in the Service object.
service.type ClusterIP Gitaly service type
securityContext.fsGroup 1000 Group ID under which the pod should be started
securityContext.runAsUser 1000 User ID under which the pod should be started
tolerations [] Toleration labels for pod assignment
persistence.accessMode ReadWriteOnce Gitaly persistence access mode
persistence.annotations   Gitaly persistence annotations
persistence.enabled true Gitaly enable persistence flag
persistence.matchExpressions   Label-expression matches to bind
persistence.matchLabels   Label-value matches to bind
persistence.size 50Gi Gitaly persistence volume size
persistence.storageClass   storageClassName for provisioning
persistence.subPath   Gitaly persistence volume mount path
priorityClassName   Gitaly StatefulSet priorityClassName
logging.level   Log level
logging.format json Log format
logging.sentryDsn   Sentry DSN URL - Exceptions from Go server
logging.rubySentryDsn   Sentry DSN URL - Exceptions from gitaly-ruby
logging.sentryEnvironment   Sentry environment to be used for logging
ruby.maxRss   Gitaly-Ruby resident set size (RSS) that triggers a memory restart (bytes)
ruby.gracefulRestartTimeout   Graceful period before a force restart after exceeding Max RSS
ruby.restartDelay   Time that Gitaly-Ruby memory must remain high before a restart (seconds)
ruby.numWorkers   Number of Gitaly-Ruby worker processes
shell.concurrency[]   Concurrency of each RPC endpoint Specified using keys rpc and maxPerRepo
packObjectsCache.enabled false Enable the Gitaly pack-objects cache
packObjectsCache.dir /home/git/repositories/+gitaly/PackObjectsCache Directory where cache files get stored
packObjectsCache.max_age 5m Cache entries lifespan
git.catFileCacheSize   Cache size used by Git cat-file process
prometheus.grpcLatencyBuckets   Buckets corresponding to histogram latencies on GRPC method calls to be recorded by Gitaly. A string form of the array (for example, "[1.0, 1.5, 2.0]") is required as input
statefulset.strategy {} Allows one to configure the update strategy utilized by the StatefulSet
metrics.enabled false If a metrics endpoint should be made available for scraping
metrics.port 9236 Metrics endpoint port
metrics.path /metrics Metrics endpoint path
metrics.serviceMonitor.enabled false If a ServiceMonitor should be created to enable Prometheus Operator to manage the metrics scraping, note that enabling this removes the scrape annotations
metrics.serviceMonitor.additionalLabels {} Additional labels to add to the ServiceMonitor
metrics.serviceMonitor.endpointConfig {} Additional endpoint configuration for the ServiceMonitor
metrics.metricsPort   DEPRECATED Use metrics.port

Chart configuration examples


extraEnv allows you to expose additional environment variables in all containers in the pods.

Below is an example use of extraEnv:

  SOME_KEY: some_value
  SOME_OTHER_KEY: some_other_value

When the container is started, you can confirm that the environment variables are exposed:

env | grep SOME


extraEnvFrom allows you to expose additional environment variables from other data sources in all containers in the pods.

Below is an example use of extraEnvFrom:

      fieldPath: spec.nodeName
      containerName: test-container
      resource: requests.cpu
      name: special-secret
      key: special_token
      # optional: boolean
      name: useful-config
      key: some-string
      # optional: boolean


pullSecrets allows you to authenticate to a private registry to pull images for a pod.

Additional details about private registries and their authentication methods can be found in the Kubernetes documentation.

Below is an example use of pullSecrets

  repository: my.gitaly.repository
  tag: latest
  pullPolicy: Always
  - name: my-secret-name
  - name: my-secondary-secret-name


tolerations allow you schedule pods on tainted worker nodes

Below is an example use of tolerations:

- key: "node_label"
  operator: "Equal"
  value: "true"
  effect: "NoSchedule"
- key: "node_label"
  operator: "Equal"
  value: "true"
  effect: "NoExecute"


annotations allows you to add annotations to the Gitaly pods.

Below is an example use of annotations:

annotations: annotation-value


priorityClassName allows you to assign a PriorityClass to the Gitaly pods.

Below is an example use of priorityClassName:

priorityClassName: persistence-enabled

Altering security contexts

Gitaly StatefulSet performance may suffer when repositories have large amounts of files due to a known issue with fsGroup in upstream Kubernetes. Mitigate the issue by changing or fully deleting the settings for the securityContext.

      fsGroup: ""
      runAsUser: ""
The example syntax eliminates the securityContext setting entirely. Setting securityContext: {} or securityContext: does not work due to the way Helm merges default values with user provided configuration.

External Services

This chart should be attached the Workhorse service.


  serviceName: webservice
  port: 8181
Name Type Default Description
host String   The hostname of the Workhorse server. This can be omitted in lieu of serviceName.
port Integer 8181 The port on which to connect to the Workhorse server.
serviceName String