Cells

GitLab's evolving sharding architecture: split a single GitLab installation into many independent "cells", each handling a subset of organizations.

Status

Cells is partially implemented. The codebase contains:

• The Cell model (app/models/cell.rb) and Organization model (app/models/organizations/organization.rb).
• Cell-aware routing helpers (lib/gitlab/cells/).
• Topology service integration (lib/gitlab/topology_service_client/).
• An "organization scope" namespace (app/controllers/organizations/) and the URL prefix /-/organizations/<id>/.
• The classifier gems/gitlab-database-data_isolation enforces per-cell data boundaries.

The migration is incremental — most pages still operate at the global level; cell-aware behavior is gated by the gitlab_com_derisk and wip feature-flag families.

Source

app/models/cell.rb, organization.rb, organizations/
app/services/cells/                  # cell management
app/controllers/organizations/       # org-scoped endpoints
lib/gitlab/cells/                    # routing/topology helpers
gems/gitlab-database-data_isolation/ # query rejection across cells
config/feature_categories.yml         # `cell` is a feature category

Concepts

• Organization — top-level tenant inside a cell. Owns groups, projects, users (in the long term).
• Cell — a self-contained GitLab installation (own database, own runners, own object storage). Holds many organizations.
• Topology Service — central directory mapping (organization, resource) to a cell. Lives in https://gitlab.com/gitlab-org/cells/topology-service.
• Routing — Rails routes prefix /-/organizations/<id>/... to scope requests to a cell.

Data isolation

Cross-cell queries are forbidden at runtime. The data-isolation gem inspects every query and raises if it crosses an organization boundary that doesn't belong to the current cell.

Cluster-wide tables

Some tables are necessarily shared (instance-level admin settings, license metadata). They sit in a "cluster-wide" schema that all cells read from.

Related

• Database — data isolation, decomposition.
• Background — design history of cells.