What a self-managed GitLab estate includes
GitLab combines Git repositories, merge requests, issues, CI/CD pipelines, and package and container registries in one application. Self-managed means your team runs the Linux package or the Helm chart plus the services behind it: PostgreSQL, Redis, Gitaly for repository storage, object storage and a fleet of GitLab Runner hosts. Most design work sits in those services and in the CI workload.
Atlassian has announced that Jira Software, Jira Service Management, Confluence and Crowd Data Center reach end of life on March 28, 2029, while Bitbucket Data Center continues. Bitbucket users are not forced to move, but organizations replanning their Atlassian estate may use the window to decide whether source control and CI should share one self-managed platform.
Choose the edition and tier before installing
Edition and tier decide available features and valid restore targets.
| Option | What it is | Deployment effect |
|---|---|---|
| Community Edition (CE) | Built from GitLab's MIT-licensed code, without the proprietary ee directory. | No subscription and no paid-tier features. GitLab documents converting CE to EE later. |
| Enterprise Edition (EE) | Includes the proprietary ee code. Premium and Ultimate features need a paid subscription. | Choose it up front if paid features are likely. Backups restore only to the same version and edition type. |
| Free-tier features | GitLab lists instance-wide SAML SSO and Gitaly Cluster (Praefect) on the Free tier for self-managed instances. | SSO and repository-level HA do not by themselves require a subscription. |
| Premium and Ultimate features | Examples include Geo secondary sites and LDAP user and group synchronization. | Regional disaster recovery with Geo and directory-driven group membership need a subscription. |
Components that shape the design
Each component scales, fails and is backed up differently.
Rails and Sidekiq
Puma serves the web UI and API and scales horizontally. Sidekiq runs background jobs and can be split into dedicated pools as load grows.
Gitaly
Serves repository data. A single node keeps each repository on one host. Gitaly Cluster (Praefect) adds replication and needs an odd number of nodes.
PostgreSQL and Redis
PostgreSQL holds application data, with PgBouncer and Consul in multi-node setups or a managed service. Redis holds cache and job queues, with Sentinel for HA.
Object storage
Holds artifacts, LFS objects, uploads, packages and registry images. GitLab's backup command does not copy these blobs.
GitLab Runner
Executes CI jobs and is installed separately. The executor (Docker, Kubernetes, shell and others) decides how jobs are isolated.
Pick a topology and size it from load
GitLab sizes its reference architectures by requests per second, with user counts as a guide. Automation, CI and mirroring generate load that headcount does not show, so collect request rates, repository sizes, monorepo outliers and pipeline volume first, then keep monitoring after go-live.
Installs every component on virtual machines or bare metal. A single node with tested backups suits smaller environments. GitLab generally recommends a highly available design from about 3,000 users, with components split across separate nodes.
Cloud Native Hybrid runs webservice and Sidekiq in Kubernetes while PostgreSQL, Redis, Gitaly and object storage stay on virtual machines or managed services. Fully cloud native designs also run Gitaly in Kubernetes, where Gitaly Cluster is still in beta. GitLab expects strong Kubernetes knowledge for production, and OpenShift uses the GitLab Operator.
Integrate identity and harden the instance
Connect GitLab to your identity provider through SAML or OpenID Connect so sign-in, MFA and offboarding follow central policy. Test a leaver: sessions, access tokens and SSH keys should stop working. LDAP group synchronization is listed for Premium and Ultimate, so confirm the tier if membership must follow LDAP.
Restrict open sign-up and top-level group creation, keep administrator accounts separate from daily accounts, and review settings that let webhooks and integrations reach internal networks. Put TLS on every endpoint, including the container registry.
Treat runners as the highest-risk component. A CI job runs repository code with the runner's network access and any credential it can read. Separate runners for untrusted projects from those that deploy to production, avoid privileged mode unless a job requires it, keep secrets in protected and masked variables, and keep runner hosts easy to replace.
Back up the archive and the secrets
The backup command produces one archive. A working restore needs more than that file.
| Item | In the backup archive? | What to do |
|---|---|---|
| Database, repositories, wikis, uploads, CI artifacts and job logs on local storage | Yes | Schedule the backup command and copy the archive off the host. |
| /etc/gitlab/gitlab-secrets.json | No | Back it up separately. It holds the key that decrypts encrypted database data and can change after upgrades. |
| /etc/gitlab/gitlab.rb, TLS certificates and SSH host keys | No | Back them up with the secrets file. For Helm, keep values and Kubernetes secrets under the same control. |
| Object storage blobs, including registry images | No | Use the storage provider's versioning, replication or backup features. |
| Restore target | Not applicable | A backup restores only onto exactly the same version and edition type. Keep that installer package available offline. |
Plan upgrades around required stops
GitLab ships a minor release monthly and a major release about once a year. Security fixes are backported to the current and two previous monthly releases. Since GitLab 17.5, required upgrade stops fall on x.2, x.5, x.8 and x.11, and each must be installed with its background migrations finished before the next.
Use GitLab's upgrade path tool to list the stops, read each version's notes and rehearse on a restored copy of production. Back up the archive and the secrets file before each stop, and confirm runner compatibility.
From Bitbucket Server or Data Center, GitLab's importer brings across repositories, pull requests with comments and reviewers, and LFS objects. Approvals, emoji reactions and task lists are not imported, and embedded images stay linked to the old server, so keep it readable until those are handled. Converting build pipelines to .gitlab-ci.yml is separate work.
GitLab operating ownership
A self-managed GitLab instance needs named owners for the platform, the runner fleet, security controls and the change record.
Platform team
- Monitor Sidekiq queues, Gitaly latency, database replication and disk growth.
- Run scheduled backups and periodic restore tests.
- Track the next required upgrade stop.
Runner owners
- Maintain runner images, executors and autoscaling.
- Separate runners by trust level and environment.
- Remove idle runners and rotate runner tokens.
Security
- Review administrator accounts, tokens and deploy keys.
- Approve integrations, webhooks and outbound rules.
- Protect backups and the secrets file separately.
Change record
- Keep gitlab.rb or Helm values in version control.
- Log each upgrade stop and its result.
- Record edition, tier and renewal date.
GitLab deployment questions
Do we need Enterprise Edition for single sign-on?
Not for instance-wide SAML, which GitLab lists on the Free tier for self-managed instances. LDAP group synchronization is listed for Premium and Ultimate.
Can we skip versions when upgrading?
Each required stop must be installed in order, and minor versions between stops can be passed over. GitLab advises using the latest patch release of each stop.
Is Geo our disaster recovery plan?
Geo provides warm-standby secondary sites and is a Premium and Ultimate feature. Without it, recovery relies on the backup archive, the secrets file and object storage protection. Rehearse either path before relying on it.
Scope and handover
DeployOpen plans the edition, topology and sizing with your team, deploys GitLab and its runners into your cloud account, data center or isolated network, integrates SSO, hardens instance and runner settings, and sets up backups that include the secrets file. We rehearse upgrades across required stops, document the platform and can provide ongoing support. Repository migration and pipeline conversion are scoped separately.
Handover includes the chosen reference architecture and its rationale, configuration in version control, the identity and group mapping, a runner inventory by trust level, restore test results, the current version with its next required stop, and named owners for each operating area.
