Evidence ledger
28 sources
Checked 25 Sep 2026
Evidence ledger
One row per claim in Your singletons choose where you fail: ten years of GitLab's architecture: who published it, what grade it carries, when it was written, when the link was last checked, and the quote or figure it rests on. Nothing in the guide is cited from memory, so anything not in this table is not in the guide.
Topic: how GitLab's architecture changed between 2016 and 2026, read from the company's own design documents, architecture decision records and public incident reviews.
Research date: 2026-09-25. Every row was fetched in this session, through the GitLab REST API
(gitlab.com/api/v4) for file contents and issue bodies, and through the rendered page for the
URLs cited in the guide.
Evidence-base limitation, stated up front. This session's network policy allowed outbound
HTTPS to gitlab.com, github.com and a short list of package hosts, and blocked every
engineering-blog and conference host tried, including about.gitlab.com, handbook.gitlab.com,
docs.gitlab.com and the blogs of every comparable company. The hunt was therefore confined to
material GitLab publishes inside its own repositories. That is unusually rich for one company
(207 design documents, 172 labelled incident reviews) but it means the guide has two blind
spots: GitLab's own narrative blog posts, and any independent or competing account. Both are
named in the page.
| # | Org | Title | Tier | Published | Checked | URL | Claim I take from it | Supporting quote or figure |
|---|---|---|---|---|---|---|---|---|
| 1 | GitLab | Cells (design document) | adr | 2022-09-07, revised through 2026 | 2026-09-25 | https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/content/handbook/engineering/architecture/design-documents/cells/_index.md | The Cells architecture has been redesigned four times and the current iteration's goal is narrower than the original | "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." |
| 2 | GitLab | Cells (design document) | adr | 2022-09-07 | 2026-09-25 | same as #1 | Organizations are the logical boundary, Cells the physical one | "Organizations serve as logical boundaries and Cells serve as physical boundaries." |
| 3 | GitLab | Cells: Goals | adr | undated page, part of the Cells set | 2026-09-25 | https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/content/handbook/engineering/architecture/design-documents/cells/goals.md | The binding constraint is named as PostgreSQL and Redis, and partitioning and decomposition are explicitly said not to be enough | "we have estimated (internally) that the current architecture has scalability limitations, particularly for the PostgreSQL database … and Redis non-horizontally scalable resources, even when database partitioning and decomposition are taken into account." |
| 4 | GitLab | Cells: Goals | adr | — | 2026-09-25 | same as #3 | The shared-instance shape produces cross-tenant interference | "A major challenge for shared-infrastructure architectures is a lack of isolation between top-level Groups. This can lead to noisy neighbor effects." |
| 5 | GitLab | Cells ADR 001: Routing Technology using Cloudflare Workers | adr | ADR set opened 2023-12 (epic 11002) | 2026-09-25 | https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/content/handbook/engineering/architecture/design-documents/cells/decisions/001_routing_technology.md | GitLab chose a third party's edge runtime for the routing layer and recorded the dependency as a known cost | "More vendor locking with Cloudflare, but are already heavily dependent on them." |
| 6 | GitLab | Cells ADR 001 | adr | — | 2026-09-25 | same as #5 | Istio and both stateless-router proposals were considered and rejected | "We considered Istio … but concluded that it's not the right fit. We considered Request Buffering … We considered Routes Learning" |
| 7 | GitLab | Cells ADR 001 | adr | — | 2026-09-25 | same as #5 | The routing layer is expected to stay small enough to rewrite | "We don't expect this to be big risk, since we expect Routing Service to be very small and simple (up to 1000 lines of code)." |
| 8 | GitLab | Proposal: Stateless Router using Requests Buffering (rejected) | adr | rejected | 2026-09-25 | https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/content/handbook/engineering/architecture/design-documents/cells/rejected/proposal-stateless-router-with-buffering-requests.md | The rejected design's cost was duplicate request execution | "This means that each request might be sent more than once and be processed more than once as result." |
| 9 | GitLab | Proposal: Stateless Router using Routes Learning (rejected) | adr | rejected | 2026-09-25 | https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/content/handbook/engineering/architecture/design-documents/cells/rejected/proposal-stateless-router-with-routes-learning.md | GitLab deliberately keeps rejected designs published | "This documentation will be kept even if we decide not to implement this so that we can document the reasons for not choosing this approach." |
| 10 | GitLab | Cells ADR 008: Cluster wide unique database sequences | adr | — | 2026-09-25 | https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/content/handbook/engineering/architecture/design-documents/cells/decisions/008_database_sequences.md | Tenant mobility between cells forced a global identifier scheme, with five alternatives recorded | "All cells will have bigint IDs on creation. While provisioning, each of them will get a range of sequences to use from the Topology Service." |
| 11 | GitLab | Cells ADR 019: AWS Primary Region Selection for Cells Infrastructure | adr | 2025-05-08 | 2026-09-25 | https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/content/handbook/engineering/architecture/design-documents/cells/decisions/019_aws_primary_region_selection_for_cells.md | The next-generation platform is deliberately cross-cloud | "we are using AWS to provision our first Cells while maintaining critical infrastructure components like the Topology Service in GCP." |
| 12 | GitLab | Cells ADR 015: Cloud Spanner Region Configuration for Topology Service | adr | 2025-05-08 | 2026-09-25 | https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/content/handbook/engineering/architecture/design-documents/cells/decisions/015_spanner_multiregional.md | The routing control plane is a managed strongly-consistent store, not GitLab's own PostgreSQL | "The Topology Service in the Cells architecture requires a highly available database with strong consistency guarantees." |
| 13 | GitLab | Rails Monolith Decomposition | adr | created 2023-05-22, status still proposed |
2026-09-25 | https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/content/handbook/engineering/architecture/design-documents/modular_monolith/_index.md | The codebase size, and the fact that decomposition has not been accepted in three years | "It has over 2.2 million lines of Ruby code and hundreds of engineers contributing to it every day." |
| 14 | GitLab | Rails Monolith Decomposition | adr | 2023-05-22, revised 2026 | 2026-09-25 | same as #13 | The justification for decomposition has been rewritten around agents rather than scale | "This reframes modularization. It is no longer only about engineering velocity and cognitive load; it is the structural prerequisite for agentic development at scale." |
| 15 | GitLab | Database Scalability: Limit on-disk table size to < 100 GB | adr | 2021-06-23, status accepted |
2026-09-25 | https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/content/handbook/engineering/architecture/design-documents/database_size_limits/_index.md | A measurable ceiling, not a principle, is what drove a decade of database work | "we target a table size less than 100 GB for a physical table on GitLab.com (including its indexes)" and "start action to reduce table sizes when the table is around 10 GB" |
| 16 | GitLab | Database Scalability: Limit on-disk table size | adr | 2021-06-23 | 2026-09-25 | same as #15 | The size of the worst table and its growth rate | "the ci_builds table is 1.5 TB in size as of June 2021 and has 31 indexes associated with it which sum up to 1 TB in size. The overall on-disk size for this table is 2.5 TB. Currently, this grows at 300 GB per month." |
| 17 | GitLab | CI/CD Scaling | adr | 2021-01-21, status ongoing |
2026-09-25 | https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/content/handbook/engineering/architecture/design-documents/ci_scale/_index.md | CI volume and the 2012 data model are the named constraint | "we are creating more than 5 million builds each day on GitLab.com we are reaching database limits that are slowing our development velocity down." |
| 18 | GitLab | CI/CD Scaling | adr | 2021-01-21 | 2026-09-25 | same as #17 | Cumulative build counts and the stated growth target | "On February 1st, 2021, GitLab.com surpassed 1 billion CI/CD builds created. In February 2022 we reached 2 billion of CI/CD build stored in the database." and "Enable future growth by making processing 20M builds in a day possible." |
| 19 | GitLab | Scaling Git | adr | 2026-06-16, status proposed |
2026-09-25 | https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/content/handbook/engineering/architecture/design-documents/scaling-git/_index.md | Git storage is being re-architected onto object storage, ten years after the first move off NFS | "Gitaly stores the authoritative copy of a repository on the serving nodes' filesystem. Compute and storage are thus tightly coupled with one another, which makes it hard to scale either of these dimensions." |
| 20 | GitLab | Siphon | adr | 2024-11-20, status ongoing |
2026-09-25 | https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/content/handbook/engineering/architecture/design-documents/siphon/_index.md | Analytical load was moved off PostgreSQL by CDC rather than by read replicas | "delivers serialized CDC (change data capture) data from the PostgreSQL logical replication stream to a queueing system. From the queueing system, consumers can process the data and ingest it into other database systems (e.g. ClickHouse, Snowflake)." |
| 21 | GitLab | Coordinating changes in Cells | adr | 2024-07-16 | 2026-09-25 | https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/content/handbook/engineering/architecture/design-documents/cells/infrastructure/managing_changes.md | Many cells turn deployment into a sequencing problem the existing pipeline cannot express | "Merge requests and pipelines alone cannot enforce those properties; they could be building blocks of our solution, but there is a need for a coordinator engine." |
| 22 | GitLab | Cloudflare Standardization across GitLab | adr | 2025-05-20, status proposed |
2026-09-25 | https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/content/handbook/engineering/architecture/design-documents/cloudflare-standardization/_index.md | The edge dependency is spreading across teams by default rather than by decision | "GitLab's usage of Cloudflare as our preferred edge networking provider continues to grow, with several teams implementing solutions for DNS management, WAF configuration, and worker deployments across our infrastructure estate" |
| 23 | GitLab | Incident Review: Error rates violating SLO (INC-10096 / #22103) | postmortem | 2026-05-12 | 2026-09-25 | https://gitlab.com/gitlab-com/gl-infra/production/-/work_items/22108 | One worker's jobs exhausted the shared Redis and took the platform down | "At its worst, the Sidekiq queue backlog reached over 12 million jobs, causing pipeline creation and job processing to stall." and "Earlier mitigation for a previous incident led to audit event jobs being deferred, which then accumulated and consumed all available memory on the Redis Sidekiq cluster." |
| 24 | GitLab | Incident Review: Redis primary CPU saturation on redis-sidekiq nodes | postmortem | 2026-05-20 (incident 2026-05-19) | 2026-09-25 | https://gitlab.com/gitlab-com/gl-infra/production/-/work_items/22170 | The same worker nearly repeated the outage a week later; Redis's own shape is the ceiling | "Redis memory grew from normal levels to 35 GiB before intervention. Redis's single-threaded architecture limited CPU scaling, compounding the resource bottleneck." |
| 25 | GitLab | Incident review: Slow Gitaly operations on gitlab.com and gitlab-org 500 errors | postmortem | 2026-03-24 | 2026-09-25 | https://gitlab.com/gitlab-com/gl-infra/production/-/work_items/21629 | A single stateful storage node still owns the availability of everything on it | "A single Gitaly storage node (gitaly-cny-01-stor-gprd.c.gitlab-production.internal) experienced a sharp spike in anonymous memory usage, leading to degraded performance. After rebooting the node as mitigation, it failed to mount its data disk" |
| 26 | GitLab | Incident Review: (Gitlab.com is down) INC-6113 | postmortem | 2025-12-05 | 2026-09-25 | https://gitlab.com/gitlab-com/gl-infra/production/-/work_items/20942 | The edge dependency accepted in ADR 001 was measured 22 months later | "Customers Affected: All SaaS users", "Requests Affected: All public API's, ~155 million requests", "Total Duration |
| 27 | GitLab | Incident review for 2022-11-30: GitLab.com site-wide outage | postmortem | 2022-11-30 | 2026-09-25 | https://gitlab.com/gitlab-com/gl-infra/production/-/work_items/8100 | The change path, not the request path, produced the worst full outage in the corpus | "An engineer triggered a routine task using our tools on a local development environment that … resulted in performing a change to production that took down a core component (Consul) of our Postgres HA solution (Patroni)." and "Our CDN reports ~13M requests that resulted in 503 during the outage." |
| 28 | GitLab | Gitaly README | source | continuously updated | 2026-09-25 | https://gitlab.com/gitlab-org/gitaly/-/blob/master/README.md | Gitaly's stated goal, and the completion of the ten-year migration of Git access behind an RPC boundary | "Fault-tolerant horizontal scaling of Git storage in GitLab, and particularly, on GitLab.com." and "All application code accesses Git repositories via Gitaly." |
| 29 | GitLab | Gitaly: Transactions | source | current on master |
2026-09-25 | https://gitlab.com/gitlab-org/gitaly/-/blob/master/doc/transactions.md | The transactional storage layer is running on GitLab.com but is not generally available and warns about data loss | "Transactions enabled. Transactions are an experimental feature. The feature is not production ready yet and might lead to various issues including data loss." |
| 30 | GitLab | Gitaly: High Availability (HA) Design | source | long-running design doc | 2026-09-25 | https://gitlab.com/gitlab-org/gitaly/-/blob/master/doc/design_ha.md | Praefect's shape: a routing front end plus quorum voting over Gitaly nodes | "Praefect - a transparent front end to all Gitaly shards. This reverse proxy ensures that all gRPC calls are forwarded to the correct shard by consulting the coordinator." |
| 31 | GitLab | Merge request 8895: "Remove raft, wal, transactions" (closed, unmerged) | source | opened 2026-06-10 | 2026-09-25 | https://gitlab.com/gitlab-org/gitaly/-/merge_requests/8895 | A 365-file change deleting the entire transactional storage layer was opened and closed without merging, six days before the object-storage proposal was published | "Removes raft, transactions, wal and associated helpers, CLI tools" ; state closed, merged_at: null, changes_count 365 |
| 32 | GitLab | cells-mailroom/ in the main Rails repository |
source | current on master |
2026-09-25 | https://gitlab.com/gitlab-org/gitlab/-/tree/master/cells-mailroom | Cells is no longer only a design document; cell-specific code sits at the root of the monolith | directory present in the repository tree listing alongside app, ee, workhorse, sidekiq_cluster |
| 33 | Git project | Documentation/technical/reftable | source | current on master |
2026-09-25 | https://github.com/git/git/blob/master/Documentation/technical/reftable.adoc | The upstream Git change GitLab's storage plan depends on, and why ref storage is a scaling problem at all | "Some repositories contain a lot of references (e.g. android at 866k, rails at 31k). The existing packed-refs format takes up a lot of space (e.g. 62M), and does not scale with additional references." |
| 34 | GitLab | Capacity planning (Tamland) | adr | 2023-09-11, status implemented |
2026-09-25 | https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/content/handbook/engineering/architecture/design-documents/capacity_planning/_index.md | Saturation forecasting is a named, owned artefact rather than a dashboard habit | "Tamland predicts SLO violations and their respective dates, which need to be reviewed and acted upon." |
| 35 | GitLab | Design document index (207 entries) and incident-review issues (172) | source | live | 2026-09-25 | https://gitlab.com/gitlab-com/gl-infra/production/-/work_items | The size of the public record this guide is built from | x-total: 172 on the incident-review label; 207 entries under content/handbook/engineering/architecture/design-documents |
Tier mix
- postmortem: 5 (rows 23-27)
- adr: 17
- source: 6
- blog: 0 (host blocked)
- paper: 0
- talk: 0
- vendor: 0
Distinct hosts: 2 (gitlab.com, github.com). This is below the breadth this format normally
asks for and the reason is stated in the page: the network policy in this session blocked every
other candidate host, and GitLab's primary record happens to live on one of the two that
remained.
Queries that worked
https://gitlab.com/api/v4/projects/gitlab-com%2Fgl-infra%2Fproduction/issues?labels=incident-review&per_page=50
https://gitlab.com/api/v4/projects/gitlab-com%2Fgl-infra%2Fproduction/issues?search=Incident%20Review&in=title&state=closed&sort=asc
https://gitlab.com/api/v4/projects/gitlab-com%2Fcontent-sites%2Fhandbook/repository/tree?path=content/handbook/engineering/architecture/design-documents&per_page=100
https://gitlab.com/api/v4/projects/gitlab-org%2Fgitaly/merge_requests?state=closed&order_by=updated_at
https://gitlab.com/api/v4/projects/<ns%2Fproject>/repository/files/<url-encoded-path>/raw?ref=main