Cells

This page contains information related to upcoming products, features, and functionality. It is important to note that the information presented is for informational purposes only. Please do not rely on this information for purchasing or planning purposes. The development, release, and timing of any products, features, or functionality may be subject to change or delay and remain at the sole discretion of GitLab Inc.
Status Authors Coach DRIs Owning Stage Created
ongoing ayufan fzimmer DylanGriffith lohrc tkuah sxuereb ayufan tkuah daveyleach devops tenant scale 2022-09-07

This document is a work-in-progress and represents a very early state of the Cells design. Significant aspects are not documented, though we expect to add them in the future.

Cells is a new architecture for our software as a service platform. This architecture is horizontally scalable, resilient, and provides a more consistent user experience. It may also provide additional features in the future, such as data residency control (regions) and federated features.

Goals

See Goals, Glossary and Requirements.

Protocells

Protocells is the current iteration of the Cells architecture, replacing the earlier Cells 1.0, Cells 1.5, and Cells 2.0 iterations with a new focus on permanently reducing load on the legacy cell’s database.

Summary

Protocells relieves the legacy cell’s databases by providing horizontal scalability.

Organizations serve as logical boundaries and Cells serve as physical boundaries.

This design integrates three key components: Organizations, Organization Migration, and Cells Infrastructure.

Progress is tracked in the working epic.

Proposal

flowchart TD
    subgraph P1["1 · Organizations"]
        A["Top-level group\n+ child resources"] -->|"transferred to"| B["Organization"]
        B --> C["Missing references\nrender gracefully\non source & target cell"]
    end

    subgraph P2["2 · Organization Migration"]
        D["Organization"] -->|"all data, no loss"| E["New Cell"]
        E -->|"canonical cell updated"| F["Topology Service"]
    end

    subgraph P3["3 · Cells Infrastructure"]
        G["Incoming Request"] -->|"routed by org"| H["Routing Logic"]
        H -->|"lookup"| F
        F -->|"cell location"| H
        H -->|"proxy"| E
    end

    B -.->|"migrate"| D
    A ~~~ G

Protocells is built on three pillars:

Pillar Purpose Result
1. Organizations Introduce Organizations as the logical boundary with Organization Isolation. A top-level group, and its child resources (groups, projects and users, and so on) are transferred to its own Organization.
2. Organization Migration Enable the movement of Organizations between Cells through the Organization Data Migration design document. All data for an Organization are moved from one cell to another, without data loss. The canonical cell for that Organization is updated in Topology Service to switch over.
3. Cells Infrastructure Deploy multiple self-contained GitLab instances as Cells on GitLab.com through the Cells Infrastructure design document. Routing logic directs requests to the appropriate Cell based on Organization.

Pillar details:

Pillar Details
1. Organizations Prevents data and operations from crossing Organization boundaries, with Organization context resolution established for all requests. On Self-Managed and Dedicated, a one-to-one mapping between instance and Organization is established through the Organization ADR. When an Organization is moved to another Cell, pages on both the source and target Cell continue to render when references are missing. For example, an issue whose author (User) was not moved together with the Organization, or a comment made by a moved user on an issue in another Organization.
2. Organization Migration This tooling supports migrating Organizations from the Legacy Cell to new Cells. It enables horizontal scalability and load distribution across the infrastructure.
3. Cells Infrastructure Each Cell is capable of hosting multiple Organizations. Cells operate as independent GitLab instances with their own databases and infrastructure.

This effort does not preclude other complementary efforts to support the legacy cell’s database, such as Data Retention.

Design and Implementation Details

Logical vs. Physical Boundaries

The architecture distinguishes between two types of boundaries:

Logical Boundary (Organization): Defines data sharding boundary (e.g. PostgreSQL, Gitaly) and access control.

Organizations are the unit of isolation for all GitLab features and data.

Physical Boundary (Cell): Defines infrastructure distribution.

Cells are self-contained GitLab instances that can host multiple Organizations.

This separation enables:

  • Organizations to move between Cells without changing their logical structure.
  • Multiple Organizations to share infrastructure on a single Cell.
  • Cross-organization operations to use public APIs.

Organization-Scoped Operations

Most operations should be scoped to an Organization.

This ensures features operate within the logical boundary and maintain isolation.

Cross-Organization Operations

All operations that span multiple Organizations must utilize public APIs.

This ensures:

  • Proper authentication and authorization boundaries.
  • Consistent behavior across deployment models.
  • Clear separation of concerns between Organizations.

Examples of cross-organization operations:

  • User authentication and session management.
  • Public API access to shared resources.
  • Administrative operations on GitLab.com.

Deployment Models

GitLab.com
  • Multiple Cells, each hosting multiple Organizations.
  • Organizations are the unit of isolation.
  • Cells are the unit of physical distribution.
  • Default Organization provides backward compatibility for existing users.
Self-Managed and Dedicated
  • Single instance per Organization (one-to-one mapping).
  • Organizations provide the logical boundary.
  • Instance provides the physical boundary.
  • Simplified operational model compared to GitLab.com.

Feature Parity

Feature parity will be required to ensure customers retain existing functionality. These efforts will focus on:

Architecture overview

@startuml

cloud "Cloudflare" as CF {
  [Routing Service Worker] as CF_RSW
}

node "GitLab Inc. Infrastructure" {
  node "Cell Services" as Cell_Services {
    [Topology Service] as TS
    [Cloud Spanner] as TS_CS

    TS --> TS_CS
  }

  node "A Cell" as Cell {
    frame "GitLab Rails" as Cell_Rails {
      [Puma + Workhorse + LB] as Cell_Puma
      [Sidekiq] as Cell_Sidekiq
    }

    [Container Registry] as Cell_Registry

    database DB as Cell_DB {
      frame "PostgreSQL Cluster" as Cell_PSQL {
        package "ci" as Cell_PSQL_ci {
          [gitlab_ci] as Cell_PSQL_gitlab_ci
        }

        package "main" as Cell_PSQL_main {
          [gitlab_main_cell_local] as Cell_PSQL_gitlab_main_cell_local
          [gitlab_main_org] as Cell_PSQL_gitlab_main_org
        }

        PC_PSQL_main -[hidden]-> Cell_PSQL_ci
      }

      frame "Redis Cluster" as Cell_Redis {
        [Redis (many)] as Cell_Redis_many
      }

      frame "Gitaly Cluster" as Cell_Gitaly {
        [Gitaly Nodes (many)] as Cell_Gitaly_many
      }
    }

    Cell_Rails -[hidden]-> Cell_DB
  }

}

CF_RSW --> Cell_Puma
CF_RSW --> Cell_Registry
CF_RSW --> Cell_Puma
CF_RSW --> Cell_Registry
CF_RSW --> TS
Cell_Puma --> TS
Cell_Sidekiq --> TS

@enduml

Future Scope

Cells 2.0’s target was to support a public and open source contribution model in a cellular architecture. Protocells narrowed the immediate focus to relieving the legacy cell’s database, so the following aspects of that original scope remain unresolved and are tracked as future scope rather than part of the current Protocells rollout:

  1. Cross-Organization interop (“Org Connect”): contributing to a public project across an Organization boundary needs an interop capability that does not exist yet. Organizations ADR 015 names this concept “Org Connect” and describes it as remaining “a long way off.”
  2. A user’s Organizations spanning multiple Cells: a user can already belong to many Organizations, but seamlessly using Organizations that live on different Cells depends on the New Auth Stack (GATE), which has not been deployed yet. This is a sequencing dependency rather than an open design question.
  3. Migrating public Organizations between Cells: migrating an Organization between Cells is in scope for Protocells (see Cells: Data migration), but today only private Organizations are realistic candidates. Public Organizations depend on features that “travel” via internal APIs and assume same-cluster reachability, such as forking via Gitaly repository-to-repository operations. Migrating a public Organization to a different Cell would break those assumptions, so this needs its own rework before public-Organization migration is possible.

Technical proposals

The Cells architecture has long lasting implications to data processing, location, scalability and the GitLab architecture. This section links all different technical proposals that are being evaluated.

Impacted features

The Cells architecture will impact many features requiring some of them to be rewritten, or changed significantly. Below is a list of known affected features with preliminary proposed solutions.

Impacted features: Placeholders

The following list of impacted features only represents placeholders that still require work to estimate the impact of Cells and develop solution proposals.

Frequently Asked Questions

What’s the difference between Cells architecture and GitLab Dedicated?

We’ve captured individual thoughts and differences between Cells and Dedicated over here

The new Cells architecture is meant to scale GitLab.com. The way to achieve this is by moving Organizations into Cells, but different Organizations can still share server resources, even if the application provides isolation from other Organizations. But all of them still operate under the existing GitLab SaaS domain name gitlab.com. Also, Cells still share some common data, like users, and routing information of Groups and Projects. For example, no two users can have the same username even if they belong to different Organizations that exist on different Cells.

With the aforementioned differences, GitLab Dedicated is still offered at higher costs due to the fact that it’s provisioned with dedicated server resources for each customer, while Cells use shared resources. This makes GitLab Dedicated more suited for bigger customers, and GitLab Cells more suitable for small to mid-size companies that are starting on GitLab.com.

On the other hand, GitLab Dedicated is meant to provide a completely isolated GitLab instance for any Organization. This instance is running on its own custom domain name, and is totally isolated from any other GitLab instance, including GitLab SaaS. For example, users on GitLab Dedicated don’t have to have a different and unique username that was already taken on GitLab.com.

Can different Cells communicate with each other?

Not directly, our goal is to keep them isolated and only communicate using global services.

How are Cells provisioned?

The GitLab.com cluster of Cells uses GitLab Dedicated tooling for provisioning GitLab Instances. That’s why Cells are referred to by Tenants in some projects. Once any Cell instance gets provisioned it could join the GitLab.com cluster and become a Cell. One requirement will be that the instance does not contain any prior data. One of the reasons is that Cells save data with custom primary key ranges that they pull from the Topology Service.

cells-deployment

The Cells are managed in the tissue project, where we manage all the Cells for both dev and prod environments in the rings directory.

Each cells configuration, is validated against tenant-model-schema which is already used for GitLab dedicated tenants as well.

Deployment Process

The deployment workflow follows these steps:

  1. The instrumentor retrieves the Cell configuration, which in Dedicated Tooling known as TENANT_MODEL.
  2. Instrumentor parses the TENANT_MODEL and pass the required configuration to GET (GitLab Environment Toolkit).
  3. GET deploys the infrastructure and uses Helm Installation to install GitLab in the provisioned Kubernetes Cluster.

This approach aligns with how we deploy GitLab on the existing legacy Cell infrastructure in both Staging and Production environments through Kubernetes workloads.

To reach shared resources, Cells will use Private Service Connect.

See also the design discussion.

What is a Cells topology?

See the design discussion.

How are users of an Organization routed to the correct Cell?

TBD

Why not use subdomains, like mycorp.gitlab.com?

See All Cells are under a single GitLab.com domain. Beyond that goal, subdomains raise a few concrete issues:

  • Care must be taken to prevent security issues with cookies leaking across subdomains.
  • Complicates integrations and API interactions, as the URL and host will change based on the organization.
  • We will need to build a common login service, which will redirect users to a valid organization/URL.
  • Increased risk of naming collisions with higher impact. For example different divisions or organizations across a large enterprise, or companies with similar names.

How do users authenticate with Cells and Organizations?

See the design discussion.

How would users log in?

See the Organization Login Design Document for the current, accepted design.

  • UI: The login to Organizations would be scoped to the Organization: https://<GITLAB_DOMAIN>/users/sign_in?organization=gitlab-inc.
  • SAML: https://<GITLAB_DOMAIN>/users/auth/saml/callback would receive ?organization=gitlab-inc which would be routed to the correct Cell.
  • This would require using the dynamic routing method with a list of Organizations available using a solution with high availability.

How are Cells rebalanced?

TBD

How will we onboard users to an Organization on additional Cells?

An Admin will perform the following tasks:

  1. Create an Organization on the additional cell.
  2. Create a new user with the Owner role in the Organization.
  3. Remove the Admin from the Organization. Optional, depending on feature set.
  4. The new Owner will import data for this group. This would create users, add them to the groups/projects, and add them to the Organization.

How can Cells implement disaster recovery capabilities?

TBD

How can I adapt a feature to be compatible with Cells?

Review the draft checklist.

A more comprehensive guide is also available in this merge request.

Please do reach out to #f_protocells, or join a Protocells Office Hours session for any questions.

How can I decide if my feature can be cell-local, or clusterwide ?

By default, features are required to be scoped to the Organization level. Any deviation from that rule should be validated and approved by Tenant Scale.

The design goals of the Cells architecture describe that all Cells are under a single domain and as such, Cells are invisible to the user:

  • Cell-local features should be limited to those related to managing the Cell, but never be a feature where the Cell semantic is exposed to the customer.
  • The Cells architecture wants to freely control the distribution of Organization and customer data across Cells without impacting users when data is migrated.

Cluster-wide features are strongly discouraged because:

  • They might require storing a substantial amount of data cluster-wide which decreases scalability headroom.
  • They might require implementation of non-trivial data aggregation that reduces resilience to single node failure.
  • They are harder to build due to the need of being able to run mixed deployments. Cluster-wide features need to take this into account.
  • They might affect our ability to provide an on-premise like experience on GitLab.com.
  • Some features that are expected to be cluster-wide might in fact be better implemented using aggregation techniques that use trusted intra-cluster communication using the same user identity. For example, user Profile is shared across the cluster.
  • The Cells architecture limits what services can be considered cluster-wide. Services that might initially be cluster-wide are still expected to be split in the future to achieve full service isolation. No feature should be built to depend on such a service (like Elasticsearch).

Will Cells use the reference architecture for up to 1000 RPS or 50,000 users?

See reference architecture for up to 1000 RPS or 50,000 users.

The infrastructure team will properly size Cells depending on the load. The Tenant Scale team sees an opportunity to use GitLab Dedicated as a base for Cells deployment.

Decision log

Last modified September 17, 2026: Rationalize Protocells content between cells/_index.md and goals.md (5598ae94)
View page source - Edit this page - please contribute. Creative Commons License