Deployment

How the GitLab application is built, packaged, and rolled out.

Three deployment paths

GitLab supports several install methods, all driven from this monorepo:

1. Omnibus packages (gitlab-org/omnibus-gitlab) — single deb/rpm bundling Rails, Puma, Sidekiq, Workhorse, Gitaly, Postgres, Redis, NGINX, etc.
2. Helm charts (gitlab-org/charts/gitlab) — Kubernetes-native deployment, one Deployment per component.
3. GitLab.com (Cloud Native Hybrid) — internal Helm-based deployment. The same charts that customers use power GitLab.com.

This repo is the source of truth for application code; the Omnibus and Charts repos consume releases.

Build pipeline

graph LR
    Push[git push to master]
    CI[.gitlab-ci.yml]
    Asset[scripts/compile_assets]
    Image[docker build]
    Stage[staging.gitlab.com]
    Canary[canary.gitlab.com]
    Prod[gitlab.com]

    Push --> CI
    CI --> Asset
    Asset --> Image
    Image --> Stage
    Stage --> Canary
    Canary --> Prod

Steps:

1. Each merge to master triggers the canonical pipeline.
2. CI compiles assets (Webpack + Vite), builds Docker images, runs tests across many parallel jobs.
3. The artifacts are pushed to GitLab.com's internal registry.
4. Release Tools open MRs to bump the gitlab ref in omnibus-gitlab and charts/gitlab.
5. CD systems roll the new image to staging → canary (10% of traffic) → production.

Release cadence

GitLab ships a major release on the 22nd of every month plus patch releases as needed. Backports to stable branches use scripts/backport_fix_to_stable_branch.

Release tooling lives at https://gitlab.com/gitlab-org/release-tools.

Configuration

Each deployment path supplies configuration:

• Omnibus: /etc/gitlab/gitlab.rb → templated into config/gitlab.yml, config/database.yml, etc.
• Helm: values.yaml → ConfigMaps and Secrets → environment variables.
• GDK: gdk.yml → similar templates.

The Rails app reads canonical config from:

• config/gitlab.yml — application-level (paths, host, integrations).
• config/database.yml — Postgres connection.
• config/redis.yml — Redis URL.
• config/secrets.yml — keys, tokens.
• ENV vars — selected overrides.

Multi-environment

GitLab.com runs in many "stages":

• staging.gitlab.com — pre-production smoke.
• canary — 10% of production users.
• production.

Feature flags decouple feature rollout from code rollout; new code is dark-launched and progressively enabled per group/user.

Database migrations during deploy

Rails migrations run during deploy. The split between pre-deploy and post-deploy migrations is critical for zero-downtime rollouts:

• Pre-deploy migrations run before the new code is rolled out.
• Post-deploy migrations run after the new code is fully deployed (some manually triggered).

See Database for the full ruleset.

Self-managed updates

Self-managed customers receive patch and major releases via Omnibus / Helm. Update steps (run migrations, restart processes) are documented at https://docs.gitlab.com/ee/update/.

CI for self-managed customers

The omnibus-gitlab and gitlab-org/charts/gitlab repos run their own pipelines on each release tag, producing artifacts in their package registry / chart museum.

Related

• Database — migration safety rules.
• Architecture — process topology.
• Geo — multi-region replication strategy.