How to choose a GitLab reference architecture by users and RPS
GitLab's published reference architectures are matched on requests per second, so headcount is only the starting estimate. The documented architectures run from 1,000 users at 20 API requests per second up to 50,000 users at 1,000 API requests per second. An organization with 4,000 developers that works mostly in small repositories and runs light pipelines can land in a smaller tier than one with 2,000 developers, heavy API automation and large monorepos. Start with user count to get a range, then use measured or forecast request rates to pick the tier. This page covers how to convert headcount into an RPS estimate, how monorepos and CI load move you up a tier, and when Cloud Native deployment is a reasonable alternative to virtual machines.
The docs generally recommend a high availability strategy from 3,000 users onward, which usually means Gitaly Cluster with Praefect, PostgreSQL with Patroni, Redis Sentinel and Consul. Below that point a single well-sized Linux package server can be enough, and the decision is about recovery time and maintenance windows as much as load. Confirm the current HA guidance on the reference architectures documentation before you commit, because the recommended thresholds and component lists are the parts most likely to change between releases.
Before you select a tier, collect three numbers: active users, peak API request rate from existing tooling or your load balancer logs, and the share of work that comes from CI runners, Git over SSH and HTTPS, and integrations. Ask your team to confirm whether any repository is large enough to need extra Gitaly capacity, and whether CI concurrency will rise during the next planned year. Write these assumptions down, because they become the basis for the load test that validates the choice before go-live.
Which reference architecture fits which profile
This table compares the 1K to 50K user reference architectures by the API request rate each targets, the high availability expectation and the typical fit. Use the user count as a starting point, then move up a tier when monorepos or CI load push request volume past the target. Confirm request rates for the intermediate tiers in the GitLab reference architectures documentation before you size.
| Reference architecture | HA expectation | Typical fit | Consider a larger tier when |
|---|---|---|---|
| 1K users, 20 API RPS | Not generally recommended at this size | Small engineering teams with modest CI and standard repositories | Monorepos or heavy CI push request volume past the 20 RPS target |
| 3K users, confirm RPS in the documentation | High availability generally recommended from this size | First size where the standard HA layout applies | Large monorepos, high CI concurrency or heavy API automation |
| 5K users, confirm RPS in the documentation | HA expected, confirm node counts for this tier | Mid-size enterprises with several engineering groups | Gitaly or Sidekiq load grows faster than user count |
| 10K users, confirm RPS in the documentation | HA expected, confirm topology for this tier | Large organizations with many teams sharing one instance | CI concurrency or monorepo size grows after go-live |
| 25K users, confirm RPS in the documentation | HA expected, confirm topology for this tier | Very large enterprises with many business units | Load testing shows sustained request load above the tier target |
| 50K users, 1,000 API RPS | HA expected, with the largest documented topology | Largest tier in the reference architectures | Only after load testing confirms the tier fits your capacity plan |
How monorepos and CI load change the sizing decision
User count gives a starting reference architecture, but the workload behind those users can move the answer. The factors below change how much Gitaly, Sidekiq, the database and the runner fleet work, so measure them before you commit to a size.
Large monorepos and Gitaly load
Repository size, history depth and clone or fetch volume fall on Gitaly, not on the Rails tier. A large monorepo with heavy CI cloning can push Gitaly well beyond what a user count suggests, which affects whether you need Gitaly Cluster or sharded Gitaly. Measure repository size, clone frequency from pipelines and Gitaly resource use during peak hours before you choose a layout. See the sibling topic on scaling GitLab for large monorepos.
CI job concurrency and runner polling
Concurrent pipelines create API requests from runners that poll for jobs, and that polling counts toward the requests per second the reference architecture targets. A team with modest headcount but many parallel jobs can outgrow a size chosen by users alone. Record peak concurrent jobs, runner polling intervals and API request rates from your current system, then compare them with the published RPS targets.
Automation and API integrations
Bots, chat notifications, issue sync jobs and custom tooling that call the API add load that headcount does not capture. Scripts that page through large projects or poll for status can be costly. Inventory every integration and service account that calls GitLab, estimate their request rates from logs, and include them in your RPS figure. The GitLab integrations content group covers the connections in detail.
Geographic spread
Teams in several regions may need local access to Git repositories, which can push you toward a Geo secondary site or a different topology. Geo provides a warm-standby secondary site that is continuously synchronized, which serves disaster recovery and is not a general replacement for a sizing decision. Confirm which teams need low-latency access, where the primary must sit, and whether recovery goals justify a secondary.
Sidekiq job volume
Background jobs for notifications, merge request processing, repository housekeeping and webhooks run on Sidekiq. Growth in job volume raises Sidekiq demand and memory use independently of web traffic, so a deployment can need more background capacity before its web tier is saturated. Watch queue depth and job throughput over a normal week, and check whether Sidekiq should run on separate nodes at your scale. The sibling topic on sizing Sidekiq covers the per-process guidance.
Validate the choice with a load test
Published targets describe the workload the reference architecture was designed for, not yours. Before go-live or after a major change, run the GitLab Performance Tool against your environment and read the results against the RPS target for your user count. Treat the result as evidence for the decision, and rerun the test when repository size, CI volume or integrations change materially.
When to pick Cloud Native Hybrid over VMs
The Linux package is GitLab's most mature installation method and bundles PostgreSQL, Redis and Sidekiq alongside the application, so every component runs on servers you manage directly. This model suits teams that already run virtual machines, configuration management and backup tooling, and that want a single, well-documented upgrade path for the whole stack.
- Familiar operations: Your team applies OS patches, manages
gitlab.rband runs upgrades with tools it already uses for other services. - Direct control of stateful nodes: Gitaly, PostgreSQL and Redis sit on machines you can inspect, resize and snapshot according to your own standards.
- Clear split of roles: Rails, Sidekiq, Gitaly and database nodes are separate VMs, which makes capacity planning and failure isolation easier to explain to auditors.
- Scaling by adding nodes: Growth in the reference architectures means adding VMs with defined roles rather than rebuilding a cluster.
- Upgrade coordination: Required upgrade stops and zero-downtime steps must be run across several hosts, so plan maintenance windows and rehearse them.
Check that your team has the Linux administration depth to run high availability components such as Patroni, Sentinel and Consul before choosing this path.
The Cloud Native Hybrid architecture runs stateless components, such as Webservice and Sidekiq, on Kubernetes, while stateful services stay outside the cluster on VMs or managed services. GitLab's reference architecture documentation states that running stateful components such as PostgreSQL and Redis inside Kubernetes is not supported, so the cluster is a compute layer, not a data layer. This model fits organizations that already operate Kubernetes well and want GitLab's application tier to follow the same deployment practices.
- Kubernetes competence: Your platform team should already handle cluster upgrades, node pools, ingress, secrets and autoscaling before adding GitLab to the cluster.
- Managed stateful services: Decide early which PostgreSQL, Redis and object storage services you will use, and confirm each is supported for the role.
- Split responsibility: Stateful VMs or managed services still need backups, patching and failover, so the cluster does not remove that work.
- Helm-based delivery: Chart values, version pinning and rollback procedures become part of your change management.
- Network design: Connectivity between cluster and stateful services must be planned for latency, DNS and security groups.
Confirm the supported component versions and the current Cloud Native Hybrid guidance in the reference architecture documentation before committing to a design.
Some organizations need GitLab in an environment with restricted outbound access, or they want managed database and cache services rather than self-operated ones. GitLab documents running self-managed instances in offline, air-gapped environments, with separate guidance for security scanners and GitLab Duo Self-Hosted. Managed services can reduce the number of stateful systems your team runs, but they change the set of supported configurations and the points at which you depend on a provider.
- Offline installation planning: Package mirrors, container images, scanner data and upgrade bundles must be staged inside the boundary before go-live.
- Managed database fit: Check the supported PostgreSQL and Redis options against the reference architecture you are targeting, and confirm extensions and version requirements.
- Recovery dependencies: Managed services carry their own backup and restore behavior, so test restores end to end with GitLab's backup procedure.
- Compliance evidence: Auditors will ask who operates each tier, so document the responsibility split between your team and the provider.
- Feature availability: Some scanners and AI features behave differently offline, so confirm what is in scope for your edition.
Ask the vendor or your architect to confirm which managed services are supported for each role in your target reference architecture.
The deciding factors are usually organizational rather than technical. A team that runs a mature Kubernetes platform, has GitOps habits and can staff on-call for stateful services may find the hybrid model simpler. A team with strong VM automation and limited container experience will often find the Linux package easier to operate. Neither model removes the need for backups, monitoring, load testing and planned upgrades.
- Existing platform: If your organization already standardizes on a Kubernetes distribution, GitLab's application tier can reuse those pipelines and controls.
- Operations capacity: Estimate who will patch databases, rotate certificates and respond to alerts for each stateful tier.
- Security tooling: Check whether your secrets, logging and policy tools integrate more easily with VMs or with the cluster.
- Change management: Consider how each model fits your approval and maintenance window practices.
- Exit and portability: Consider how hard it would be to move between models later, since stateful data stays in place in both.
Before choosing, ask a partner or GitLab for a written component map showing where each role runs, who operates it and how it is backed up.
How to size and validate your reference architecture
This sequence turns a user count and a rough picture of activity into a shortlisted GitLab reference architecture, a deployment model, and a load test that confirms the choice before go-live. Each step leaves a written record that the next step can check.
Inventory users and activity patterns
Platform owners list active users, not just licensed seats, and split them by role, time zone and working pattern. Include bots, service accounts and any external collaborators who clone or push. Record the peak hour and the largest working day you expect, since sizing follows peaks rather than averages. The step is done when the team can state how many users are active in a typical peak hour and why.
Measure or estimate API requests per second
Estimate requests per second from your own traffic where possible, using load balancer or existing Git host logs, and treat that figure as the input that matters more than headcount. Where no history exists, say so in writing and use a conservative estimate with a stated basis. Confirm the definition of RPS used in the reference architecture documentation, because the published targets refer to API requests per second. The output is a single RPS figure with its source attached.
Estimate CI concurrency and repository size
Count the pipelines you expect to run at the same time at peak, and the jobs each pipeline starts. Note the largest repositories and whether any are monorepos with heavy Git operations, since these load Gitaly regardless of user count. Ask your engineering leads for the CI volume they expect in the next budget cycle, and record it. The step is complete when concurrency and repository profile are written next to the RPS figure, so the shortlist can account for them.
Shortlist the reference architecture
Compare the RPS and user figures against the published reference architectures, which run from 1,000 users at 20 requests per second to 50,000 users at 1,000 requests per second. Use the higher of the user-based and RPS-based tiers, and move up a tier when monorepos or heavy CI push the load past what the tier was designed for. Check the current table in the reference architecture documentation rather than relying on memory. The output is a named tier with notes on any adjustments.
Decide between VMs and Cloud Native Hybrid
Decide whether your platform team will run the stateful services on virtual machines, or run the stateless components on Kubernetes with PostgreSQL, Redis and Gitaly outside the cluster. The documentation states that PostgreSQL and Redis inside Kubernetes are not supported, so the choice depends on existing Kubernetes skills and on whether managed cloud services are approved for your data. Confirm the current support statement before you decide. The step is done when the deployment model and its owners are recorded.
Confirm high availability and disaster recovery needs
Review whether the organization needs high availability at the tier you selected. The documentation generally recommends a high availability strategy at 3,000 users or more, using Gitaly Cluster with Praefect, PostgreSQL with Patroni, Redis Sentinel and Consul. Decide separately whether a Geo secondary site is required for disaster recovery, and note that Geo requires Premium or Ultimate. Ask your compliance and continuity owners to confirm recovery objectives in writing. The output is a list of HA and DR decisions that the build plan can reference.
Record sizing assumptions and validate with the performance tool
Write down every input, source and assumption from the previous steps, including the chosen tier, deployment model and any monorepo or CI adjustments. Run the GitLab Performance Tool against the built environment before go-live, and again after significant changes, then read the results against the RPS targets for the tier. If results fall short, adjust the tier or components and repeat the test. The step is complete when the test report and the assumption record are signed off by the platform owner.
Security and operational factors in the sizing decision
The reference architecture you pick sets more than server counts. It also sets how much hardening, backup, upgrade and runner work your team owns. Review these five areas before you commit to a size, because each one grows with the number of nodes and stateful services you run.
Hardening scope by tier
A single-node instance has one set of settings in gitlab.rb and one operating system to harden. A high availability layout multiplies that surface across Rails, Sidekiq, Gitaly, PostgreSQL, Redis and Consul nodes, so each role needs its own configuration review. GitLab's hardening guidance covers application settings, CI/CD, configuration files and the operating system, and says it should be rolled out gradually. Ask who owns configuration drift across every node before you size.
Offline and air-gapped constraints
If your network blocks outbound access, the architecture decision also decides where packages, container images and scanner data come from. GitLab documents offline installations, and it has separate guidance for security scanners and GitLab Duo Self-Hosted in offline environments. Each additional stateful node is another component you must mirror and patch without internet access. Confirm which features your tier includes and which need offline-specific setup before you pick a layout.
Backup and restore planning
Backups must cover every stateful tier in the chosen layout, including repository storage, the database, object storage and the secrets file. In a Gitaly Cluster layout, the documented backup approach differs from sharded Gitaly, so restore time depends on that choice. Ask for a tested restore procedure with timings measured in your environment, not only a successful backup log. Keep recovery targets and the restore runbook in the same review as the sizing decision.
Upgrade stops and maintenance windows
GitLab requires upgrades to pass through required upgrade stops, which fall at versions x.2, x.5, x.8 and x.11 since GitLab 17.5. A larger high availability layout takes longer to move between those stops, and zero-downtime upgrades require every component to support rolling updates. Plan one maintenance window per required stop, and confirm with your own runbook which steps are downtime-free for your layout. Check the maintenance policy so you know which releases receive security backports.
Runner isolation and fleet scope
Runners execute your CI/CD jobs, so their placement changes the blast radius of a compromised job. A larger user base and heavier CI load usually mean more runners, autoscaling and separate executor types, each with its own hardening and version alignment. GitLab advises keeping Runner major and minor versions aligned with GitLab. Decide whether shared and project runners run on isolated hosts, and size the runner fleet separately from the GitLab application tier.
What to confirm before you commit to a size
What reference architecture sizes sit between 1,000 and 50,000 users?
The published reference architectures run from 1,000 users at 20 API requests per second to 50,000 users at 1,000 requests per second, and the intermediate tiers have their own user and request targets. Confirm the exact figures for the tier you are considering on the reference architectures page, because the tier tables are updated with releases and should be read for the GitLab version you will deploy. Use the tier that matches your measured request rate, then check whether your CI load and monorepo size push you higher.
Can PostgreSQL and Redis run inside a Kubernetes cluster for GitLab?
No. GitLab's reference architecture documentation says running stateful components such as PostgreSQL and Redis inside Kubernetes is not supported. The Cloud Native Hybrid architecture runs stateless components such as Webservice and Sidekiq on Kubernetes, while stateful services stay on virtual machines or managed services. Confirm this against the current reference architecture page before you design the cluster, and ask your platform team which managed database and cache services fit your cloud or data center.
Is Gitaly Cluster with Praefect worth its complexity for my repositories?
Gitaly Cluster with Praefect adds repository-level replication and failover, but it brings operational and backup trade-offs that belong in the decision. Check GitLab's current documentation for its known limitations, its backup approach, and its status on Kubernetes before you commit. Ask your team how much repository downtime they can tolerate, how they will take backups that cover all replicas, and whether a sharded Gitaly layout meets the same goals with less overhead.
Which Geo disaster recovery features are included in each GitLab tier?
GitLab Geo is available in the Premium and Ultimate tiers for self-managed GitLab, and it provides a warm-standby secondary site in another region that is continuously synchronized. The Free tier does not include Geo. Confirm the current tier mapping on the GitLab pricing page and the Geo documentation, then decide whether a secondary site, a cold backup and restore plan, or both meet your recovery time expectations.
Which GitLab version should I plan for given the maintenance policy?
Plan for the version that is currently maintained and the next required upgrade stop, not the newest release. GitLab ships a major release yearly, a minor release on the third Thursday of each month and patch releases twice a month, and currently maintains 19.5, 19.4 and 19.3. Bug fixes are backported only to the current stable release, while security fixes also go to the previous two monthly releases. Check the maintenance policy page for the current list, and confirm required upgrade stops on the upgrade paths page before you fix a target version.
Which GitLab Runner version should match my GitLab instance?
Keep Runner major and minor versions aligned with your GitLab instance, as the GitLab Runner documentation advises. Plan the Runner upgrade in the same change window as the GitLab upgrade so that the fleet does not drift across required upgrade stops. Confirm the current Runner release that matches your target GitLab version on the Runner documentation, and test one Runner on the new version before you roll it out to autoscaling or Kubernetes executors.
Does my organization need a load test before go-live at a given size?
Yes, when the sizing is based on forecasts rather than measured traffic, a load test against the reference architecture targets reduces the chance that the chosen tier is wrong. GitLab publishes a k6-based Performance Tool for this purpose. Ask your team to measure current API request rates, CI job concurrency and largest repository size, then compare them with the tier targets. Plan the test window and the environment that mirrors production before you finalize hardware or cloud sizing.
Can a self-managed GitLab reference architecture run without internet access?
GitLab documents running self-managed instances in offline and air-gapped environments, with separate guidance for its security scanners and for GitLab Duo Self-Hosted. Confirm which features you need, since some scanners and AI capabilities have their own offline steps. Ask your team how packages, container images, runner images and security database updates will reach the network, because these decide whether the chosen architecture can be maintained without outbound access.
How DeployOpen scopes and delivers GitLab sizing work
DeployOpen starts from the written user count, peak API request rate, repository sizes and CI load, then maps them to a reference architecture before any hardware is ordered. The work is planned, built and checked inside your own cloud accounts, data centers or air-gapped network.
How we scope
- Confirm user counts, peak API requests per second, largest repositories and expected CI concurrency before choosing a reference architecture
- Record whether the decision is Linux package on VMs or Cloud Native Hybrid, and which stateful services stay on VMs or managed services
- Agree deliverables, exclusions and timelines in writing, since most engagements are fixed-scope
How we build
- Build the chosen layout in your environment, including Gitaly, PostgreSQL, Redis, Sidekiq and Rails node roles
- Configure runner capacity and resource settings against the planned CI load and monorepo profile
- Run load tests against the reference architecture targets and record results against the requests per second assumptions
How we hand over
- Deliver a sizing record that explains the scoring inputs, the chosen architecture and the known limits of that choice
- Document the upgrade path, required upgrade stops and the signals that would trigger a resize
- Walk your platform and operations teams through the runbooks so they can run and expand the instance
How we support
- Offer ongoing support, upgrades and testing as a retainer after handover, scoped in writing
- Re-check sizing when user growth, repository size or CI concurrency changes materially
- Confirm support terms, response expectations and included services with the written scope before work starts
