Reference

Environment Variables¶

Type: Reference (Information-oriented)

Overview¶

GitLab BDA configuration uses a hybrid approach:

Static configuration: config.yaml (domains, versions, resource limits)
Secrets: External Secrets Operator (passwords, API keys, tokens)
Environment variables: Runtime configuration injected into pods

This document lists all environment variables used by GitLab BDA components.

GitLab Webservice¶

Database Connection¶

# PostgreSQL connection (via Pooler)
GITLAB_DATABASE_HOST=gitlab-postgres-pooler
GITLAB_DATABASE_PORT=5432
GITLAB_DATABASE_NAME=gitlab
GITLAB_DATABASE_USERNAME=app
GITLAB_DATABASE_PASSWORD=<from secret: gitlab-postgres-app>

# Alternative: Connection URI
DATABASE_URL=postgresql://app:<password>@gitlab-postgres-pooler:5432/gitlab

Redis Connection¶

# Redis cache + job queue
REDIS_URL=redis://redis:6379/0

# Separate databases for different purposes
GITLAB_REDIS_CACHE_URL=redis://redis:6379/0
GITLAB_REDIS_QUEUES_URL=redis://redis:6379/1
GITLAB_REDIS_SHARED_STATE_URL=redis://redis:6379/2

S3 Object Storage¶

# S3 credentials (from secret: gitlab-s3-credentials)
AWS_ACCESS_KEY_ID=<from secret>
AWS_SECRET_ACCESS_KEY=<from secret>

# S3 configuration
GITLAB_S3_ENDPOINT=https://fsn1.your-objectstorage.com
GITLAB_S3_REGION=fsn1

# Bucket names
GITLAB_S3_ARTIFACTS_BUCKET=artifacts-gitlabbda-kup6s
GITLAB_S3_UPLOADS_BUCKET=uploads-gitlabbda-kup6s
GITLAB_S3_LFS_BUCKET=lfs-gitlabbda-kup6s
GITLAB_S3_PAGES_BUCKET=pages-gitlabbda-kup6s
GITLAB_S3_REGISTRY_BUCKET=registry-gitlabbda-kup6s
GITLAB_S3_BACKUPS_BUCKET=backups-gitlabbda-kup6s

SMTP Email¶

# SMTP configuration
GITLAB_SMTP_ADDRESS=mail.example.com
GITLAB_SMTP_PORT=587
GITLAB_SMTP_USER_NAME=gitlab@example.com
GITLAB_SMTP_PASSWORD=<from secret: gitlab-smtp-password>
GITLAB_SMTP_DOMAIN=example.com
GITLAB_SMTP_AUTHENTICATION=login
GITLAB_SMTP_ENABLE_STARTTLS_AUTO=true

GitLab Configuration¶

# External URL
GITLAB_EXTERNAL_URL=https://gitlab.staging.bluedynamics.eu

# Pages domain
GITLAB_PAGES_DOMAIN=pages.staging.bluedynamics.eu
GITLAB_PAGES_EXTERNAL_HTTPS=true

# SSH configuration
GITLAB_SHELL_SSH_PORT=22

Feature Flags¶

# Optional features
GITLAB_PROMETHEUS_METRICS_ENABLED=true
GITLAB_SENTRY_ENABLED=false
GITLAB_USAGE_PING_ENABLED=false

GitLab Sidekiq¶

Sidekiq inherits most Webservice environment variables, plus:

# Concurrency (number of jobs processed simultaneously)
SIDEKIQ_CONCURRENCY=10

# Memory killer (restart worker if memory exceeds limit)
SIDEKIQ_MEMORY_KILLER_MAX_RSS=2000000  # 2GB in KB

# Queue selection (which job queues to process)
SIDEKIQ_QUEUE_SELECTOR=*  # All queues

GitLab Gitaly¶

# Gitaly configuration
GITALY_LISTEN_ADDR=0.0.0.0:8075
GITALY_PROMETHEUS_LISTEN_ADDR=0.0.0.0:9236

# Git configuration
GITALY_GIT_CONFIG_OPTIONS=core.fsyncObjectFiles=true

# Repository storage path
GITALY_STORAGE_PATH=/home/git/repositories

# Logging
GITALY_LOG_LEVEL=info
GITALY_LOG_FORMAT=json

GitLab Shell (SSH)¶

# SSH configuration
GITLAB_SHELL_CONFIG_FILE=/etc/gitlab-shell/config.yml
GITLAB_SHELL_LOG_LEVEL=INFO

# Internal API endpoint
GITLAB_SHELL_INTERNAL_API_URL=http://gitlab-webservice:8080/api/v4/internal

# SSH authorized keys
GITLAB_SHELL_AUTHORIZED_KEYS_FILE=/home/git/.ssh/authorized_keys

GitLab Pages¶

# Pages daemon configuration
GITLAB_PAGES_DOMAIN=pages.staging.bluedynamics.eu
GITLAB_PAGES_LISTEN_HTTP=0.0.0.0:8090
GITLAB_PAGES_LISTEN_HTTPS=0.0.0.0:8091

# S3 backend
GITLAB_PAGES_OBJECT_STORE_ENABLED=true
GITLAB_PAGES_OBJECT_STORE_CONNECTION__PROVIDER=AWS
GITLAB_PAGES_OBJECT_STORE_CONNECTION__ENDPOINT=https://fsn1.your-objectstorage.com
GITLAB_PAGES_OBJECT_STORE_CONNECTION__AWS_ACCESS_KEY_ID=<from secret>
GITLAB_PAGES_OBJECT_STORE_CONNECTION__AWS_SECRET_ACCESS_KEY=<from secret>
GITLAB_PAGES_OBJECT_STORE_BUCKET=pages-gitlabbda-kup6s

GitLab Runner¶

# Runner configuration
RUNNER_NAME=gitlab-runner
RUNNER_EXECUTOR=kubernetes
RUNNER_REQUEST_CONCURRENCY=3

# GitLab connection
GITLAB_URL=https://gitlab.staging.bluedynamics.eu
RUNNER_REGISTRATION_TOKEN=<from secret: gitlab-runner-token>

# Kubernetes executor configuration
KUBERNETES_NAMESPACE=gitlabbda
KUBERNETES_IMAGE=alpine:latest
KUBERNETES_PRIVILEGED=false

# Runner cache (S3)
CACHE_TYPE=s3
CACHE_S3_SERVER_ADDRESS=fsn1.your-objectstorage.com
CACHE_S3_BUCKET_NAME=cache-gitlabbda-kup6s
CACHE_S3_ACCESS_KEY=<from secret>
CACHE_S3_SECRET_KEY=<from secret>

PostgreSQL (CNPG)¶

Primary Instance¶

# PostgreSQL configuration
PGDATA=/var/lib/postgresql/data/pgdata
POSTGRES_USER=postgres
POSTGRES_PASSWORD=<generated by CNPG>

# CNPG operator variables
PGPORT=5432
PGHOST=/controller/run

# Backup configuration (Barman Cloud Plugin)
BARMAN_CLOUD_ENDPOINT=https://fsn1.your-objectstorage.com
BARMAN_CLOUD_BUCKET=postgresbackups-gitlabbda-kup6s
AWS_ACCESS_KEY_ID=<from secret: gitlab-s3-credentials>
AWS_SECRET_ACCESS_KEY=<from secret: gitlab-s3-credentials>

Pooler (PgBouncer)¶

# PgBouncer configuration
PGBOUNCER_LISTEN_ADDR=0.0.0.0
PGBOUNCER_LISTEN_PORT=5432
PGBOUNCER_POOL_MODE=transaction
PGBOUNCER_MAX_CLIENT_CONN=1000
PGBOUNCER_DEFAULT_POOL_SIZE=25
PGBOUNCER_RESERVE_POOL_SIZE=5

Redis¶

# Redis server configuration
REDIS_PORT=6379
REDIS_BIND=0.0.0.0

# Persistence
REDIS_SAVE=900 1 300 10 60 10000
REDIS_APPENDONLY=yes
REDIS_APPENDFSYNC=everysec

# Memory management
REDIS_MAXMEMORY=512mb
REDIS_MAXMEMORY_POLICY=allkeys-lru

# Logging
REDIS_LOGLEVEL=notice

Harbor Core¶

# Harbor configuration
HARBOR_EXTERNAL_URL=https://registry.staging.bluedynamics.eu
HARBOR_CORE_URL=http://harbor-core:8080
HARBOR_JOBSERVICE_URL=http://harbor-jobservice:8080

# Database connection
POSTGRESQL_HOST=gitlab-postgres-pooler
POSTGRESQL_PORT=5432
POSTGRESQL_USERNAME=harbor
POSTGRESQL_PASSWORD=<from CNPG-generated secret: harbor-db-app>
POSTGRESQL_DATABASE=harbor

# Redis connection
REDIS_URL=redis://redis:6379/2

# S3 storage
REGISTRY_STORAGE_S3_ACCESSKEY=<from secret: harbor-s3-credentials>
REGISTRY_STORAGE_S3_SECRETKEY=<from secret: harbor-s3-credentials>
REGISTRY_STORAGE_S3_REGION=fsn1
REGISTRY_STORAGE_S3_REGIONENDPOINT=https://fsn1.your-objectstorage.com
REGISTRY_STORAGE_S3_BUCKET=registry-gitlabbda-kup6s

# OAuth (GitLab)
AUTH_MODE=oidc_auth
OIDC_NAME=GitLab
OIDC_ENDPOINT=https://gitlab.staging.bluedynamics.eu
OIDC_CLIENT_ID=<from secret: harbor-secrets>
OIDC_CLIENT_SECRET=<from secret: harbor-secrets>
OIDC_SCOPE=openid,profile,email
OIDC_VERIFY_CERT=true
OIDC_AUTO_ONBOARD=true
OIDC_USER_CLAIM=preferred_username

Harbor Registry¶

# Registry configuration
REGISTRY_HTTP_ADDR=0.0.0.0:5000
REGISTRY_HTTP_SECRET=<from secret: harbor-secrets>
REGISTRY_LOG_LEVEL=info

# Storage backend (S3)
REGISTRY_STORAGE=s3
REGISTRY_STORAGE_S3_ACCESSKEY=<from secret: harbor-s3-credentials>
REGISTRY_STORAGE_S3_SECRETKEY=<from secret: harbor-s3-credentials>
REGISTRY_STORAGE_S3_REGION=fsn1
REGISTRY_STORAGE_S3_REGIONENDPOINT=https://fsn1.your-objectstorage.com
REGISTRY_STORAGE_S3_BUCKET=registry-gitlabbda-kup6s
REGISTRY_STORAGE_CACHE_BLOBDESCRIPTOR=redis
REGISTRY_STORAGE_CACHE_BLOBDESCRIPTORSIZE=10000

# Redis cache
REGISTRY_REDIS_ADDR=redis:6379
REGISTRY_REDIS_DB=2

Environment Variable Sources¶

From Secrets (External Secrets Operator)¶

# Example: GitLab Webservice environment
env:
  - name: GITLAB_DATABASE_PASSWORD
    valueFrom:
      secretKeyRef:
        name: gitlab-postgres-app
        key: password
  - name: AWS_ACCESS_KEY_ID
    valueFrom:
      secretKeyRef:
        name: gitlab-s3-credentials
        key: AWS_ACCESS_KEY_ID

From ConfigMaps¶

# Example: GitLab configuration
env:
  - name: GITLAB_EXTERNAL_URL
    valueFrom:
      configMapKeyRef:
        name: gitlab-config
        key: external_url

From Downward API (Pod metadata)¶

# Example: Pod name/namespace
env:
  - name: POD_NAME
    valueFrom:
      fieldRef:
        fieldPath: metadata.name
  - name: POD_NAMESPACE
    valueFrom:
      fieldRef:
        fieldPath: metadata.namespace

Environment Variable Precedence¶

GitLab uses this precedence (highest to lowest):

Environment variables (runtime)
gitlab.rb configuration file (compiled into image)
Default values (GitLab defaults)

Example: GITLAB_DATABASE_HOST environment variable overrides gitlab_rails['db_host'] in gitlab.rb.

Setting Environment Variables¶

Via CDK8S (Recommended)¶

// In CDK8S construct
const deployment = new KubeDeployment(this, 'webservice', {
  spec: {
    template: {
      spec: {
        containers: [{
          name: 'webservice',
          env: [
            {
              name: 'GITLAB_DATABASE_HOST',
              value: 'gitlab-postgres-pooler',
            },
            {
              name: 'GITLAB_DATABASE_PASSWORD',
              valueFrom: {
                secretKeyRef: {
                  name: 'gitlab-postgres-app',
                  key: 'password',
                },
              },
            },
          ],
        }],
      },
    },
  },
});

Via Helm Values (GitLab Chart)¶

# values.yaml
global:
  psql:
    host: gitlab-postgres-pooler
    port: 5432
    database: gitlab
    username: app
    password:
      secret: gitlab-postgres-app
      key: password
  redis:
    host: redis
    port: 6379
  minio:
    enabled: false  # Use external S3
  appConfig:
    object_store:
      enabled: true
      connection:
        secret: gitlab-s3-credentials
        key: connection

Via Kubectl (Manual override)¶

# Patch deployment to add environment variable
kubectl set env deployment/gitlab-webservice \
  -n gitlabbda \
  NEW_VARIABLE=value

# Edit deployment directly
kubectl edit deployment gitlab-webservice -n gitlabbda

Debugging Environment Variables¶

View Environment Variables in Running Pod¶

# List all environment variables
kubectl exec -it <pod-name> -n gitlabbda -- env

# View specific variable
kubectl exec -it <pod-name> -n gitlabbda -- printenv GITLAB_DATABASE_HOST

# Check variable in GitLab Rails console
kubectl exec -it deploy/gitlab-webservice -n gitlabbda -- \
  gitlab-rails runner 'puts Gitlab.config.gitlab.host'

View Environment Variables in Deployment¶

# Show all environment variables in deployment spec
kubectl get deployment gitlab-webservice -n gitlabbda -o json \
  | jq '.spec.template.spec.containers[].env'

# Show secrets referenced
kubectl get deployment gitlab-webservice -n gitlabbda -o json \
  | jq '.spec.template.spec.containers[].env[] | select(.valueFrom.secretKeyRef)'

Common Issues¶

Variable Not Applied¶

Symptom: Changed environment variable, but pod behavior unchanged

Cause: Pod not restarted after change

Solution:

kubectl rollout restart deployment/<deployment-name> -n gitlabbda

Secret Reference Not Found¶

Symptom: Pod crash with Error: secret "xyz" not found

Diagnosis:

# Check if secret exists
kubectl get secret <secret-name> -n gitlabbda

# Check if secret is synced (ESO)
kubectl get externalsecret -n gitlabbda

Solution:

# Wait for ESO to sync, or force sync
kubectl annotate externalsecret <name> -n gitlabbda \
  force-sync="$(date +%s)" --overwrite

Wrong Database Host¶

Symptom: connection refused errors for PostgreSQL

Common mistake: Using localhost instead of gitlab-postgres-pooler

Solution: Update GITLAB_DATABASE_HOST to Kubernetes service name

Summary¶

Environment variable architecture:

Static config: config.yaml → ConfigMaps
Secrets: ESO → Kubernetes Secrets → Pod environment
Runtime: Hardcoded values in CDK8S constructs

Key variables:

Database: GITLAB_DATABASE_* (connection details)
Redis: REDIS_URL (cache connection)
S3: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY (object storage)
SMTP: GITLAB_SMTP_* (email configuration)

For configuration values, see Configuration Reference. For secret management, see Secrets Reference.