This is one stop global knowledge base where you can learn about all the products, solutions and support features.
This page has links to online versions of the GitLab documentation.
To browse a version that is not available online, see the offline archives.
They’re available for download so that you can browse through them locally.
The default version of this website
is built from the documentation directories on the default branches of:
All of these are brought together by the
GitLab Docs project, which regularly
deploys this content to docs.gitlab.com.
In certain scenarios (i.e. offline environments), you may want to bring your own images rather than pulling them down from the Internet. This requires specifying your own Docker image registry/repository for each of the charts that make up the GitLab release.
Our default format for the image in most cases includes the full path to the image, excluding the tag:
image:
repository: repo.example.com/image
tag: custom-tag
The end result will be repo.example.com/image:custom-tag.
There is an example values file that demonstrates how to configure a custom Docker registry/repository and tag. You can copy relevant sections of this file for your own releases.
We’ll make use of the Omnibus GitLab package for Ubuntu. This package provides versions of the services that are guaranteed to be compatible with the charts’ services.
Create a VM on your provider of choice, or locally. This was tested with VirtualBox, KVM, and Bhyve.
Ensure that the instance is reachable from the cluster.
Install Ubuntu Server onto the VM that you have created. Ensure that openssh-server is installed, and that all packages are up to date.
Configure networking and a hostname. Make note of the hostname/IP, and ensure it is both resolvable and reachable from your Kubernetes cluster.
Be sure firewall policies are in place to allow traffic.
Follow the installation instructions for Omnibus GitLab. When you perform the package installation, do not provide the EXTERNAL_URL= value. We do not want automatic configuration to occur, as we’ll provide a very specific configuration in the next step.
Create a minimal gitlab.rb file to be placed at /etc/gitlab/gitlab.rb. Be very explicit about what is enabled on this node, use the contents below.
Note: This example is not intended to provide PostgreSQL for scaling.
NOTE: The values below should be replaced
DB_USERNAME default username is gitlabDB_PASSSWORD unencoded valueDB_ENCODED_PASSWORD encoded value of DB_PASSWORD. Can be generated by replacing DB_USERNAME and DB_PASSWORD with real values in: echo -n 'DB_PASSSWORDDB_USERNAME' | md5sum - | cut -d' ' -f1AUTH_CIDR_ADDRESS configure the CIDRs for MD5 authentication, should be the smallest possible subnets of your cluster or it’s gateway. For minikube, this value is 192.168.100.0/12# Change the address below if you do not want PG to listen on all available addresses
postgresql['listen_address'] = '0.0.0.0'
# Set to approximately 1/4 of available RAM.
postgresql['shared_buffers'] = "512MB"
# This password is: `echo -n '${password}${username}' | md5sum - | cut -d' ' -f1`
# The default username is `gitlab`
postgresql['sql_user_password'] = "DB_ENCODED_PASSWORD"
# Configure the CIDRs for MD5 authentication
postgresql['md5_auth_cidr_addresses'] = ['AUTH_CIDR_ADDRESSES']
# Configure the CIDRs for trusted authentication (passwordless)
postgresql['trust_auth_cidr_addresses'] = ['127.0.0.1/24']
## Configure gitlab_rails
gitlab_rails['auto_migrate'] = false
gitlab_rails['db_username'] = "gitlab"
gitlab_rails['db_password'] = "DB_PASSSWORD"
## Disable everything else
sidekiq['enable'] = false
puma['enable'] = false
registry['enable'] = false
gitaly['enable'] = false
gitlab_workhorse['enable'] = false
nginx['enable'] = false
prometheus_monitoring['enable'] = false
redis['enable'] = false
After creating gitlab.rb, we’ll reconfigure the package with gitlab-ctl reconfigure. Once the task has completed, check the running processes with gitlab-ctl status. The output should appear as such:
# gitlab-ctl status
run: logrotate: (pid 4856) 1859s; run: log: (pid 31262) 77460s
run: postgresql: (pid 30562) 77637s; run: log: (pid 30561) 77637s
For a production-ready GitLab chart deployment, use an external database.
Prerequisites:
gitlabhq_production by default.pg_trgm and btree_gist extensions. If you don’t provide an account withNetworking prerequisites:
If you plan to use PostgreSQL as a load balancing cluster and Kubernetes
DNS for service discovery, when you install the bitnami/postgresql chart,
use --set slave.service.clusterIP=None.
This setting configures the PostgreSQL secondary service as a headless service to
allow DNS A records to be created for each secondary instance.
For an example of how to use Kubernetes DNS for service discovery,
see examples/database/values-loadbalancing-discover.yaml.
To configure the GitLab chart to use an external database:
Set the following parameters:
postgresql.install: Set to false to disable the embedded database.global.psql.host: Set to the hostname of the external database, can be a domain or an IP address.global.psql.password.secret: The name of the secret that contains the database password for the gitlab user.global.psql.password.key: Within the secret, the key that contains the password.Optional. The following items can be further customized if you are not using the defaults:
global.psql.port: The port the database is available on. Defaults to 5432.global.psql.database: The name of the database.global.psql.username: The user with access to the database.Optional. If you use a mutual TLS connection to the database, set the following:
global.psql.ssl.secret: A secret that contains the client certificate, key, and certificate authority.global.psql.ssl.serverCA: In the secret, the key that refers to the certificate authority (CA).global.psql.ssl.clientCertificate: In the secret, the key that refers to the client certificate.global.psql.ssl.clientKey: In the secret, the client.When you deploy the GitLab chart, add the values by using the --set flag. For example:
helm install gitlab gitlab/gitlab
--set postgresql.install=false
--set global.psql.host=psql.example
--set global.psql.password.secret=gitlab-postgresql-password
--set global.psql.password.key=postgres-password
The instructions here make use of the Omnibus GitLab package for Ubuntu.
This package provides versions of the services that are guaranteed to be compatible with the charts’ services.
Create a VM on your provider of choice, or locally. This was tested with VirtualBox, KVM, and Bhyve.
Ensure that the instance is reachable from the cluster.
Install Ubuntu Server onto the VM that you have created. Ensure that openssh-server is installed, and that all packages are up to date.
Configure networking and a hostname. Make note of the hostname/IP, and ensure it is both resolvable and reachable from your Kubernetes cluster.
Be sure firewall policies are in place to allow traffic.
Follow the installation instructions for Omnibus GitLab. When you perform the package installation, do not provide the EXTERNAL_URL= value. We do not want automatic configuration to occur, as we’ll provide a very specific configuration in the next step.
Create a minimal gitlab.rb file to be placed at /etc/gitlab/gitlab.rb. Be
very explicit about what’s enabled on this node, using the following contents
based on the documentation for
running Gitaly on its own server.
NOTE: The values below should be replaced
AUTH_TOKEN should be replaced with the value in the gitaly-secret secretGITLAB_URL should be replaced with the URL of the GitLab instanceSHELL_TOKEN should be replaced with the value in the gitlab-shell-secret secret# Avoid running unnecessary services on the Gitaly server
postgresql['enable'] = false
redis['enable'] = false
nginx['enable'] = false
puma['enable'] = false
sidekiq['enable'] = false
gitlab_workhorse['enable'] = false
grafana['enable'] = false
gitlab_exporter['enable'] = false
gitlab_kas['enable'] = false
# If you run a seperate monitoring node you can disable these services
prometheus['enable'] = false
alertmanager['enable'] = false
# If you don't run a seperate monitoring node you can
# Enable Prometheus access & disable these extra services
# This makes Prometheus listen on all interfaces. You must use firewalls to restrict access to this address/port.
# prometheus['listen_address'] = '0.0.0.0:9090'
# prometheus['monitor_kubernetes'] = false
# If you don't want to run monitoring services uncomment the following (not recommended)
# node_exporter['enable'] = false
# Prevent database connections during 'gitlab-ctl reconfigure'
gitlab_rails['auto_migrate'] = false
# Configure the gitlab-shell API callback URL. Without this, `git push` will
# fail. This can be your 'front door' GitLab URL or an internal load
# balancer.
gitlab_rails['internal_api_url'] = 'GITLAB_URL'
gitlab_shell['secret_token'] = 'SHELL_TOKEN'
# Make Gitaly accept connections on all network interfaces. You must use
# firewalls to restrict access to this address/port.
# Comment out following line if you only want to support TLS connections
gitaly['listen_addr'] = "0.0.0.0:8075"
# Authentication token to ensure only authorized servers can communicate with
# Gitaly server
gitaly['auth_token'] = 'AUTH_TOKEN'
git_data_dirs({
'default' => {
'path' => '/var/opt/gitlab/git-data'
},
'storage1' => {
'path' => '/mnt/gitlab/git-data'
},
})
# To use TLS for Gitaly you need to add
gitaly['tls_listen_addr'] = "0.0.0.0:8076"
gitaly['certificate_path'] = "path/to/cert.pem"
gitaly['key_path'] = "path/to/key.pem"
After creating gitlab.rb, reconfigure the package with gitlab-ctl reconfigure.
Once the task has completed, check the running processes with gitlab-ctl status.
The output should appear as such:
# gitlab-ctl status
run: gitaly: (pid 30562) 77637s; run: log: (pid 30561) 77637s
run: logrotate: (pid 4856) 1859s; run: log: (pid 31262) 77460s
This document intends to provide documentation on how to configure this Helm chart with an external Gitaly service.
If you don’t have Gitaly configured, for on-premise or deployment to VM,
consider using our Omnibus GitLab package.
Disable the gitaly chart and the Gitaly service it provides, and point the other services to the external service.
You need to set the following properties:
global.gitaly.enabled: Set to false to disable the included Gitaly chart.global.gitaly.external: This is an array of external Gitaly service(s).global.gitaly.authToken.secret: The name of the secret which contains the token for authentication.global.gitaly.authToken.key: The key within the secret, which contains the token content.The external Gitaly services will make use of their own instances of GitLab Shell.
Depending your implementation, you can configure those with the secrets from this
chart, or you can configure this chart’s secrets with the content from a predefined
source.
You may need to set the following properties:
global.shell.authToken.secret: The name of the secret which contains secret for GitLab Shell.global.shell.authToken.key: The key within the secret, which contains the secret content.A complete example configuration, with two external services (external-gitaly.yml):
global:
gitaly:
enabled: false
external:
- name: default # required
hostname: node1.git.example.com # required
port: 8075 # optional, default shown
- name: praefect # required
hostname: ha.git.example.com # required
port: 2305 # Praefect uses port 2305
tlsEnabled: false # optional, overrides gitaly.tls.enabled
authToken:
secret: external-gitaly-token # required
key: token # optional, default shown
tls:
enabled: false # optional, default shown
Example installation using the above configuration file in conjunction other
configuration via gitlab.yml:
helm upgrade --install gitlab gitlab/gitlab \
-f gitlab.yml \
-f external-gitaly.yml
If your implementation uses multiple Gitaly nodes external to these charts,
you can define multiple hosts as well. The syntax is slightly different, as
to allow the complexity required.
An example values file is provided, which shows the
appropriate set of configuration. The content of this values file is not
interpreted correctly via --set arguments, so should be passed to Helm
with the -f / --values flag.
If your external Gitaly server listens over TLS port,
you can make your GitLab instance communicate with it over TLS. To do this, you
have to
Create a Kubernetes secret containing the certificate of the Gitaly
server
kubectl create secret generic gitlab-gitaly-tls-certificate --from-file=gitaly-tls.crt=<path to certificate>
Add the certificate of external Gitaly server to the list of
custom Certificate Authorities
In the values file, specify the following
global:
certificates:
customCAs:
- secret: gitlab-gitaly-tls-certificate
or pass it to the helm upgrade command using --set
--set global.certificates.customCAs[0].secret=gitlab-gitaly-tls-certificate
To enable TLS for all Gitaly instances, set global.gitaly.tls.enabled: true.
global:
gitaly:
tls:
enabled: true
To enable for instances individually, set tlsEnabled: true for that entry.
global:
gitaly:
external:
- name: default
hostname: node1.git.example.com
tlsEnabled: true
customCAs to avoid