Using the GitLab Shell chart

The gitlab-shell sub-chart provides an SSH server configured for Git SSH access to GitLab.


This chart depends on access to the Workhorse services, 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

In order to easily support SSH replicas, and avoid using shared storage for the SSH authorized keys, we are using the SSH AuthorizedKeysCommand to authenticate against the GitLab authorized keys endpoint. As a result, we don’t persist or update the AuthorizedKeys file within these pods.


The gitlab-shell chart is configured in two parts: external services, and chart settings. The port exposed through Ingress is configured with, and defaults to 22. The Service’s external port is also controlled by

Installation command line options

annotations Pod annotations
podLabels Supplemental Pod labels. Will not be used for selectors.
common.labels Supplemental labels that are applied to all objects created by this chart.
config.clientAliveInterval0Interval between keepalive pings on otherwise idle connections; the default value of 0 disables this ping
config.loginGraceTime60Specifies amount of time that the server will disconnect after if the user has not successfully logged in
config.maxStartups.full100SSHd refuse probability will increase linearly and all unauthenticated connection attempts would be refused when unauthenticated connections number will reach specified number
config.maxStartups.rate30SSHd will refuse connections with specified probability when there would be too many unauthenticated connections (optional)
config.maxStartups.start10SSHd will refuse connection attempts with some probability if there are currently more than the specified number of unauthenticated connections (optional)
config.proxyProtocolfalseEnable PROXY protocol support for the gitlab-sshd daemon
config.proxyPolicy"use"Specify policy for handling PROXY protocol. Value must be one of use, require, ignore, reject
config.proxyHeaderTimeout"500ms"The maximum duration gitlab-sshd will wait before giving up on reading the PROXY protocol header. Must include units: ms, s, or m.
config.ciphers[,,, aes128-ctr, aes192-ctr, aes256-ctr]Specify the ciphers allowed.
config.kexAlgorithms[curve25519-sha256,, ecdh-sha2-nistp256, ecdh-sha2-nistp384, ecdh-sha2-nistp521, diffie-hellman-group14-sha256, diffie-hellman-group14-sha1]Specifies the available KEX (Key Exchange) algorithms.
config.macs[,, hmac-sha2-256, hmac-sha2-512, hmac-sha1]Specifies the available MAC (message authentication code algorithms.
config.gssapi.enabledfalseEnable GSS-API support for the gitlab-sshd daemon
config.gssapi.keytab.secret The name of a Kubernetes secret holding the keytab for the gssapi-with-mic authentication method
config.gssapi.keytab.keykeytabKey holding the keytab in the Kubernetes secret
config.gssapi.krb5Config Content of the /etc/krb5.conf file in the GitLab Shell container
config.gssapi.servicePrincipalName The Kerberos service name to be used by the gitlab-sshd daemon
deployment.livenessProbe.initialDelaySeconds10Delay before liveness probe is initiated
deployment.livenessProbe.periodSeconds10How often to perform the liveness probe
deployment.livenessProbe.timeoutSeconds3When the liveness probe times out
deployment.livenessProbe.successThreshold1Minimum consecutive successes for the liveness probe to be considered successful after having failed
deployment.livenessProbe.failureThreshold3Minimum consecutive failures for the liveness probe to be considered failed after having succeeded
deployment.readinessProbe.initialDelaySeconds10Delay before readiness probe is initiated
deployment.readinessProbe.periodSeconds5How often to perform the readiness probe
deployment.readinessProbe.timeoutSeconds3When the readiness probe times out
deployment.readinessProbe.successThreshold1Minimum consecutive successes for the readiness probe to be considered successful after having failed
deployment.readinessProbe.failureThreshold2Minimum consecutive failures for the readiness probe to be considered failed after having succeeded
deployment.strategy{}Allows one to configure the update strategy utilized by the deployment
deployment.terminationGracePeriodSeconds30Seconds that Kubernetes will wait for a pod to forcibly exit
enabledtrueShell enable flag
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
hpa.behavior{scaleDown: {stabilizationWindowSeconds: 300 }}Behavior contains the specifications for up- and downscaling behavior (requires autoscaling/v2beta2 or higher)
hpa.customMetrics[]Custom metrics contains the specifications for which to use to calculate the desired replica count (overrides the default use of Average CPU Utilization configured in targetAverageUtilization)
hpa.cpu.targetTypeAverageValueSet the autoscaling CPU target type, must be either Utilization or AverageValue
hpa.cpu.targetAverageValue100mSet the autoscaling CPU target value
hpa.cpu.targetAverageUtilization Set the autoscaling CPU target utilization
hpa.memory.targetType Set the autoscaling memory target type, must be either Utilization or AverageValue
hpa.memory.targetAverageValue Set the autoscaling memory target value
hpa.memory.targetAverageUtilization Set the autoscaling memory target utilization
hpa.targetAverageValue  DEPRECATED Set the autoscaling CPU target value
image.pullPolicyIfNotPresentShell image pull policy
image.pullSecrets Secrets for the image repository image repository
image.tagmasterShell image tag
init.image.repository initContainer image
init.image.tag initContainer image tag
init.containerSecurityContext initContainer container specific securityContext
logging.formatjsonSet to text for unstructured logs
logging.sshdLogLevelERRORLog level for underlying SSH daemon
priorityClassName  Priority class assigned to pods.
replicaCount1Shell replicas
serviceLabels{}Supplemental service labels
service.externalTrafficPolicyClusterShell service external traffic policy (Cluster or Local)
service.internalPort2222Shell internal port
service.nodePort Sets shell nodePort if set
service.namegitlab-shellShell service name
service.typeClusterIPShell service type
service.loadBalancerIP IP address to assign to LoadBalancer (if supported)
service.loadBalancerSourceRanges List of IP CIDRs allowed access to LoadBalancer (if supported)
securityContext.fsGroup1000Group ID under which the pod should be started
securityContext.runAsUser1000User ID under which the pod should be started
securityContext.fsGroupChangePolicy Policy for changing ownership and permission of the volume (requires Kubernetes 1.23)
containerSecurityContext Override container securityContext under which the container is started
containerSecurityContext.runAsUser1000Allow to overwrite the specific security context under which the container is started
sshDaemonopensshSelects which SSH daemon would be run, possible values (openssh, gitlab-sshd)
tolerations[]Toleration labels for pod assignment
workhorse.serviceNamewebserviceWorkhorse service name (by default, Workhorse is a part of the webservice Pods / Service)
metrics.enabledfalseIf a metrics endpoint should be made available for scraping (requires sshDaemon=gitlab-sshd).
metrics.port9122Metrics endpoint port
metrics.path/metricsMetrics endpoint path
metrics.serviceMonitor.enabledfalseIf 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.annotations  DEPRECATED Set explicit metrics annotations. Replaced by template content.

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:

  tag: latest
  pullPolicy: Always
  - name: my-secret-name
  - name: my-secondary-secret-name


deployment.livenessProbe and deployment.readinessProbe provide a mechanism to help control the termination of Pods under some scenarios.

Larger repositories benefit from tuning liveness and readiness probe times to match their typical long-running connections. Set readiness probe duration shorter than liveness probe duration to minimize potential interruptions during clone and push operations. Increase terminationGracePeriodSeconds and give these operations more time before the scheduler terminates the pod. Consider the example below as a starting point to tune GitLab Shell pods for increased stability and efficiency with larger repository workloads.

    initialDelaySeconds: 10
    periodSeconds: 20
    timeoutSeconds: 3
    successThreshold: 1
    failureThreshold: 10
    initialDelaySeconds: 10
    periodSeconds: 5
    timeoutSeconds: 2
    successThreshold: 1
    failureThreshold: 3
  terminationGracePeriodSeconds: 300

Reference the official Kubernetes Documentation for additional details regarding this configuration.


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 GitLab Shell pods.

Below is an example use of annotations

annotations: annotation-value

External Services

This chart should be attached the Workhorse service.


  serviceName: webservice
  port: 8181
hostString The hostname of the Workhorse server. This can be omitted in lieu of serviceName.
portInteger8181The port on which to connect to the Workhorse server.
serviceNameStringwebserviceThe name of the service which is operating the Workhorse server. By default, Workhorse is a part of the webservice Pods / Service. If this is present, and host is not, the chart will template the hostname of the service (and current .Release.Name) in place of the host value. This is convenient when using Workhorse as a part of the overall GitLab chart.

Chart settings

The following values are used to configure the GitLab Shell Pods.


The name of the Kubernetes secret to grab the SSH host keys from. The keys in the secret must start with the key names ssh_host_ in order to be used by GitLab Shell.


GitLab Shell uses an Auth Token in its communication with Workhorse. Share the token with GitLab Shell and Workhorse using a shared Secret.

 secret: gitlab-shell-secret
 key: secret
authToken.keyString The name of the key in the above secret that contains the auth token.
authToken.secretString The name of the Kubernetes Secret to pull from.

LoadBalancer Service

If the service.type is set to LoadBalancer, you can optionally specify service.loadBalancerIP to create the LoadBalancer with a user-specified IP (if your cloud provider supports it).

You can also optionally specify a list of service.loadBalancerSourceRanges to restrict the CIDR ranges that can access the LoadBalancer (if your cloud provider supports it).

Additional information about the LoadBalancer service type can be found in the Kubernetes documentation

  type: LoadBalancer

Configuring the networkpolicy

This section controls the NetworkPolicy. This configuration is optional and is used to limit Egress and Ingress of the Pods to specific endpoints.

enabledBooleanfalseThis setting enables the NetworkPolicy
ingress.enabledBooleanfalseWhen set to true, the Ingress network policy will be activated. This will block all Ingress connections unless rules are specified.
ingress.rulesArray[]Rules for the Ingress policy, for details see and the example below
egress.enabledBooleanfalseWhen set to true, the Egress network policy will be activated. This will block all egress connections unless rules are specified.
egress.rulesArray[]Rules for the egress policy, these for details see and the example below

Example Network Policy

The gitlab-shell service requires Ingress connections for port 22 and Egress connections to various to default workhorse port 8181. This examples adds the following network policy:

  • All Ingress requests from the network on TCP port 2222 are allowed
  • All Egress requests to the network on UDP port 53 are allowed for DNS
  • All Egress requests to the network on TCP port 8181 are allowed for Workhorse
  • All Egress requests to the network on TCP port 8075 are allowed for Gitaly

Note the example provided is only an example and may not be complete

  enabled: true
    enabled: true
      - from:
        - ipBlock:
          - port: 2222
            protocol: TCP
    enabled: true
      - to:
        - ipBlock:
          - port: 8181
            protocol: TCP
          - port: 8075
            protocol: TCP
          - port: 53
            protocol: UDP