At enterprise scale, even small architecture choices can have outsized consequences. A deployment that works for a handful of teams can become a constraint once thousands of developers, repositories, and pipelines depend on it.

That makes each decision made before rollout especially consequential. For example, your:

  • Deployment model defines what your team must operate
  • Runner strategy shapes how CI/CD workloads execute and stay isolated, as well as how much operational load falls on your platform team
  • Availability targets shape redundancy and recovery
  • Workload determines how much capacity the platform needs

Together, those factors determine how well the platform can absorb growth without creating new operational constraints.

In this guide:

  • Architecture decisions to make before you scale
  • How to plan your runner strategy
  • Planning for high availability and disaster recovery
  • Where pipeline performance breaks down at scale
  • Kubernetes and cloud-native deployment considerations
  • An architecture validation checklist for platform teams
Architecture decisions to make before you scale

Your GitLab deployment model determines which parts of the platform your team must size, secure, monitor, upgrade, and recover. For enterprise deployments, the three core options are:

GitLab.com: GitLab’s multi-tenant software-as-a-service (SaaS) offering. GitLab operates the application and underlying infrastructure, while your organization manages its GitLab configuration, integrations, and any self-managed runners.

GitLab Dedicated: A fully managed, single-tenant SaaS offering hosted on Amazon Web Services (AWS). GitLab operates the underlying infrastructure, including updates, high availability, and disaster recovery; your organization controls user and data access through application-level controls.

GitLab Self-Managed: Your organization installs, administers, and maintains its own GitLab instance. You manage the infrastructure and assume responsibility for operating, scaling, securing, and recovering the environment.

Choose the model based on the control your organization requires and the infrastructure responsibility it can sustain. For example, you may want to choose:

  • GitLab.com when a multi-tenant SaaS model meets your requirements and minimizing infrastructure operations is the priority
  • GitLab Dedicated when you need single-tenant isolation or control over areas such as networking and data residency without operating the GitLab infrastructure yourself
  • GitLab Self-Managed when requirements call for direct control over the underlying infrastructure and your team has the capacity to operate the platform

Before you decide, document any requirements that could rule an option in or out. Pay particular attention to data residency, network isolation, recovery objectives, and infrastructure control. Then map the operational work each model leaves with your team, including upgrades, monitoring, capacity planning, backups, and incident response.

That exercise should clarify the central tradeoff: how much infrastructure responsibility your organization needs and can realistically own.

Once you define that operating boundary, it’s time to plan the compute layer that will execute your CI/CD workloads.

How to plan your runner strategy

GitLab Runner executes CI/CD jobs, and the GitLab application coordinates the pipelines behind them. That separation matters at enterprise scale because application capacity and runner capacity respond to different types of demand. The application handles Git, web, API, and automation traffic; the runner fleet absorbs the volume and concurrency of CI/CD work.

For this reason, you should size the runner fleet based on the workloads themselves rather than on developer headcount. Start by documenting:

  • Job volume and duration
  • Peak concurrency
  • Operating system and compute requirements
  • Network paths and specialized hardware
  • Privileged or sensitive workloads
  • Peak periods such as release windows or scheduled scans

Use those inputs to estimate how many jobs must run at once to meet your queued-duration target. Workload data matters more than team size because two organizations with the same number of developers can generate very different CI/CD demand based on pipeline frequency, automation, and job requirements.

Choose the right runner scope

Runner scope determines how broadly teams can use each pool. Instance runners can serve projects across the GitLab instance, while group runners limit access to projects and subgroups within a defined group. Project runners provide the narrowest scope and fit workloads that need dedicated credentials, specialized infrastructure, or stronger isolation. Because that capacity is reserved for fewer workloads, project runners may also sit idle when job volume is intermittent, so factor utilization into the decision.

Use the broadest scope that meets the workload’s trust and compute requirements. Broader pools generally improve utilization, while sensitive deployment jobs or specialized workloads may justify dedicated infrastructure.

Plan for autoscaling

Autoscaling lets runner capacity expand or contract with demand, but operating that infrastructure also takes platform engineering time. If you manage your own runner fleet, account for how quickly new resources become usable: instance provisioning, cloud quotas, image downloads, and cache availability can all affect queued duration during a spike. Keep enough ready capacity to absorb short-term demand while additional compute comes online.

You can also shift that operational work to GitLab. GitLab-hosted runners are available for GitLab.com and GitLab Dedicated, with GitLab managing the underlying runner infrastructure and autoscaling. For teams that want to reduce the time spent provisioning, patching, and scaling runner machines, that changes the runner strategy from an infrastructure-management decision to more of a capacity and workload-placement decision.

Match the executor to the workload

Executor choice determines where CI/CD jobs run and what infrastructure your team must operate. For cloud-native environments, the Kubernetes executor uses an existing Kubernetes cluster. For autoscaled workloads on public-cloud virtual machines, GitLab provides the Docker Autoscaler and Instance executors.

The right choice depends on the environment your jobs need and the infrastructure your team is prepared to manage. With the Kubernetes executor, each CI/CD job runs in its own pod, making cluster behavior part of runner performance. Scheduling delays, resource requests and limits, node capacity, and autoscaling can all affect how quickly jobs start and complete.

Account for those constraints in your capacity plan so the executor does not become a bottleneck as CI/CD demand grows.

Planning for high availability and disaster recovery

Availability planning should begin with the business impact of downtime and data loss. Define:

  • Service level objective (SLO): The level of service the platform should maintain during normal operation
  • Recovery time objective (RTO): How quickly service must be restored after an outage
  • Recovery point objective (RPO): How much data loss the organization can tolerate

Together, these targets define the redundancy and recovery capacity the architecture needs.

How much of that work falls to your platform team depends on the deployment model. If you use GitLab Self-Managed, your team owns those architecture decisions. Use the GitLab reference architectures as a production-ready starting point, then adapt the topology to your availability and recovery requirements.

With GitLab Dedicated, GitLab manages the underlying disaster recovery infrastructure and failover process. Customers can choose a secondary AWS region for geo-based disaster recovery, while GitLab maintains replication between the primary and secondary regions and manages failover when required.

For Self-Managed deployments, your recovery design should treat high availability, disaster recovery, and backups as distinct but complementary layers:

  • High availability limits the impact of component failures within the primary environment.
  • Disaster recovery restores service after the loss of a site or region.
  • Backups protect against corruption, deletion, and other failures that replication can carry to a secondary site.

In addition, for Self-Managed deployments, turn your recovery targets into architecture requirements. Decide where redundancy is needed, how data will replicate, and how backups will protect critical data. Include dependencies such as identity and networking services in the recovery plan.

GitLab Geo provides an active-passive disaster recovery architecture with secondary sites that synchronize from the primary. For Self-Managed, failover requires customer-managed operational steps, so rehearse the process under realistic conditions and measure the results against your RTO and RPO.

Record any failed dependencies or manual steps that could slow recovery, then use those findings to strengthen the design.

Where pipeline performance breaks down at scale

As GitLab adoption grows, performance planning shifts from sizing for expected demand to validating the platform’s behavior under real-world load. The first step is to identify where time is being lost.

GitLab separates queued duration from execution duration, which gives you a useful starting point for diagnosis. A job’s queued duration shows how long it waited to start, while job duration captures execution time. Pipeline duration measures the time spent running the pipeline and excludes pending queue time.

Those metrics point to different constraints. A high queued duration may indicate insufficient runner capacity. Longer execution times, by contrast, can stem from pipeline design, test suites, dependency downloads, or repository transfers.

Establish a performance baseline

Test representative projects under both normal and peak demand to see where performance starts to degrade. Include conditions such as release windows, scheduled security scans, and periods of heavy commit activity, then track the signals that surface the bottleneck:

  • Queued duration
  • Job and pipeline duration
  • Runner utilization
  • Retries and failures
  • Cache performance
  • Artifact transfer time
  • Infrastructure saturation

Break the results down by runner pool and workload type so organization-wide averages don’t hide bottlenecks affecting specific teams or workloads. From there, use what you learn to set thresholds for expanding runner capacity, optimizing pipelines, or scaling the GitLab application.

Test large repositories and monorepos separately

Large repositories and monorepos place distinct demands on GitLab and runner infrastructure. Frequent clones and fetches can increase CPU, memory, disk, and network usage, especially when many pipelines access the same repository simultaneously.

Look beyond repository size when estimating that impact. Clone frequency, concurrent CI/CD activity, branch patterns, and the amount of data each job transfers can all shape platform load.

Optimize the workload before scaling capacity

Pipeline design can reduce demand on the platform itself. Run independent jobs in parallel, avoid unnecessary pipelines, cache frequently downloaded dependencies, and limit artifact retention. For monorepos, trigger jobs only when relevant paths change and reduce the amount of repository data each job needs to transfer.

Continue measuring after rollout as usage evolves. For Self-Managed environments, actual resource utilization and workload patterns provide the clearest signal for when the architecture needs to scale.

Kubernetes and cloud-native deployment considerations

Kubernetes can play two different roles in a GitLab architecture. The Kubernetes executor can run CI/CD jobs as pods in an existing cluster, while GitLab Self-Managed can run in a cloud-native architecture on Kubernetes.

These choices affect different parts of the platform and should be evaluated separately. Using Kubernetes for runners changes how CI/CD compute is provisioned and scaled. Running GitLab on Kubernetes changes how your team operates the application and its supporting infrastructure.

Plan Kubernetes runners as part of the cluster

With the Kubernetes executor, a runner manager calls the Kubernetes API and creates a pod for each CI/CD job. That makes the cluster itself part of your runner architecture.

Plan the Kubernetes resources and controls those jobs will rely on, including namespaces, service accounts, resource requests and limits, and workload isolation. Sensitive deployment jobs may also require stronger separation from less-trusted build workloads.

Capacity matters just as much as configuration. Test whether cluster autoscaling can add nodes quickly enough to meet your queued-duration targets. Even when the cluster eventually provides enough compute, slow node provisioning can leave jobs waiting during demand spikes.

Choose the right architecture for GitLab on Kubernetes

Running GitLab itself on Kubernetes requires a broader architecture decision. GitLab recommends its Cloud Native reference architecture for new Self-Managed deployments. In this model, GitLab components run in Kubernetes, while PostgreSQL, Redis, and object storage remain external.

Cloud Native Hybrid remains an option when specific components need to stay outside Kubernetes. Teams that require a Gitaly Cluster for repository-level high availability, for example, should evaluate a hybrid or VM-based reference architecture because the standard Cloud Native architecture runs Gitaly in a non-clustered configuration.

Whichever model you choose, include Kubernetes in the operating plan for the wider GitLab platform. Your team will need observability across the cluster and external services, along with an upgrade process that accounts for GitLab and its infrastructure dependencies. Capacity and recovery testing should cover the cluster as part of the production environment.

The GitLab cloud-native overview provides more context on this deployment model. Choose Kubernetes when its operating model fits your infrastructure requirements, and your team has the skills to run it reliably.

An architecture validation checklist for platform teams

Use this checklist before rollout to validate the major architecture decisions across deployment, sizing, runners, recovery, and performance. For each item, document the evidence that supports the decision or assign an owner to close the gap.

What to validateEvidence or ownerDeployment modelThe selected deployment model meets data residency, isolation, networking, and customization requirements.Responsibilities are clearly divided among GitLab, your platform team, and infrastructure providers.Upgrades, maintenance, support, and capacity management have named owners and documented procedures.Application sizingExpected RPS drives the baseline architecture size for Self-Managed deployments.Sizing reflects the mix of API, web, and Git traffic.The design accounts for atypical workloads such as large monorepos or heavy automation.Runner strategyRunner sizing reflects job volume, duration, peak concurrency, and compute requirements.Runner scopes match trust boundaries, privileged access, and workload-isolation requirements.Autoscaling limits, cloud quotas, startup time, and ready capacity have been tested under peak demand.Queued-duration and pipeline-duration targets are defined and monitored separately.Runner-manager architecture avoids a single point of failure for critical workloads.Availability and recoveryBusiness and technical owners have approved SLO, RTO, and RPO targets.Redundancy, backups, replication, and failover procedures address required failure scenarios.Recovery tests include identity, DNS, secrets, networking, and external integrations.The latest recovery exercise met its objectives or has assigned remediation work.Performance and growthRepresentative projects, monorepos, security jobs, and release workloads have been tested under expected peak demand.Dashboards track queued duration, job and pipeline duration, errors, infrastructure saturation, and runner utilization.Scaling thresholds define when to add capacity or optimize workloads.The architecture has a defined review cadence for changing usage patterns and organizational requirements.

Enterprise scale puts every early architecture decision under pressure. The strongest GitLab environments reflect how the organization actually operates and leave enough room for demand to change.

Those conditions will evolve as adoption expands. Keep measuring, revisit the architecture as demand shifts, and let evidence drive the next decision. That discipline turns GitLab from a platform that simply supports more users into one that can keep pace with the organization around it.

💡 Learn how GitLab Dedicated supports enterprise scale.