Handbook

Monorepo Handbook

Design and operate a large shared repository.

Find, evaluate, and operate repository-engineering decisions by domain, symptom, or role without treating Bazel as the only mechanism.

Start with H.1 View handbook map

A shared repository concentrates leverage and contention in the same source boundary. It can make code, consumers, and coordinated change visible together; it can also concentrate access concerns, policy disputes, service failures, and delivery risk. This handbook helps you find the owner of a repository problem and choose evidence for that domain. It is a reference, not a stage after Level 6 and not an argument that every repository should become a monorepo.¹

Bazel appears where its graph, hermetic actions, affected-scope analysis, build evidence, and scalable execution implement a repository decision. Levels 0–6 teach those mechanisms. The handbook links to them instead of making Git, ownership, security, policy, and delivery sound like Bazel features. It remains useful when the repository also uses Maven, npm, pip, Go, Cargo, CMake, or a transitional mixture.

A Lens For Repository Decisions

Across all eleven domains, ask six questions. Boundary names the state and scope under decision. Identity separates the revisions, versions, artifacts, or environments that must not be conflated. Authority says who decides, approves, operates, and repairs. Evidence justifies a state transition. Transition explains staging, reversal, and recovery. Retirement says when an old mechanism, migration, or exception has actually ended.

Not every problem needs all six questions. Use the lens to find a missing part of a decision, then enter the domain that owns it rather than walking the handbook in order.

Eleven Places To Look

The first group defines the shared working boundary. H.1 Repository asks what belongs in the source boundary, how its topology and information lifecycle work, and how that boundary changes. H.2 Discovery covers finding code, supported contracts, consumers, examples, documentation, and owners. H.3 Workspace follows the local path from Git and bootstrap through feedback and degraded operation.

The next group controls change across people and graphs. H.4 Ownership separates maintenance, expertise, approval, internal and external contribution, and escalation. H.5 Dependencies defines supported internal products, allowed edges, compatibility, polyglot resolution, generated interfaces, and dependency intake. H.6 Migration operates transitions that cannot finish as one atomic edit.

The final group operates shared state and services. H.7 Integration decides which candidate evidence admits a change and how queues, speculation, flakiness, and recovery affect that decision. H.8 Policy governs standards, paved roads, rollout, reversal, and exceptions. H.9 Security separates source, execution, artifact, credential, supply-chain, and audit trust. H.10 Platform operates repository services for reliability, capacity, support, economics, and repository-product outcomes. H.11 Delivery connects source, artifacts, releases, compatibility, promotion, runtime state, and recovery.

The numbers keep navigation predictable. They do not assert that Repository is a prerequisite for Delivery or that everyone should read all eleven sections.

Diagnose From The Symptom

Start from the narrowest recognizable question. Follow a secondary link only when the first article shows that the symptom crosses a second boundary.

Symptom or question	Primary destination	Possible secondary destination
Should this code be in the same repository?	H.1.1 Repository Models	H.9.1 Source Access
A directory or namespace layout obscures boundaries or makes moves unsafe	H.1.4 Repository Topology	H.5.2 Dependency Boundaries
History, a secret, personal data, or a large object must be retained or removed	H.1.5 Information Lifecycle	H.9.5 Security Audit
Clone, status, checkout, or history is too slow	H.3.1 Git Workspace	H.10.3 Service Capacity
Code, an API, example, or owner cannot be found	H.2.1 Code Search / H.2.2 API Discovery	H.4.2 Stewardship
Documentation or a decision record looks current but is not	H.2.3 Knowledge Lifecycle	H.4.2 Stewardship
Ordinary changes require central assistance	H.3.3 Local Feedback	H.10.4 Platform Support / H.8.2 Paved Roads
Review waits on the same few people	H.4.5 Ownership Failure	H.7.4 Change Admission
An outside contribution or upstream synchronization crosses the repository boundary	H.4.6 External Contributions	H.9.2 Trust Boundaries
The graph permits accidental coupling	H.5.2 Dependency Boundaries	H.8.3 Policy Lifecycle
Old and new consumers cannot coexist safely	H.5.3 Compatibility Contracts	H.11.4 Runtime Compatibility
A dependency cannot be admitted or has become vulnerable	H.5.6 Dependency Intake	H.9.4 Supply Chain
Generated code or its generator blocks a broad change	H.5.5 Generated Interfaces	H.6.3 Migration Automation
A broad migration never finishes	H.6.4 Progress Control	H.4.2 Stewardship
A merge queue is slow or reuses evidence for the wrong state	H.7.5 Merge Queue / H.7.6 Speculation	H.7.3 Evidence Selection
Main is frequently broken or evidence is unknown	H.7.8 Main Recovery / H.7.4 Change Admission	H.10.2 Service Reliability
A repository-wide rule causes repeated exceptions	H.8.4 Policy Exceptions	the item that defines the rule's subject
Source or credentials cross the wrong trust boundary	H.9.1 Source Access / H.9.3 Credentials	H.1.1 Repository Models
Search, review, or ownership service is unavailable	H.10.2 Service Reliability	H.3.4 Degraded Workflow
Repository investment is not improving developer workflows	H.10.6 Repository Metrics	H.10.5 Economics
Co-location forces products to release together	H.11.6 Delivery Models	H.5.3 Compatibility Contracts
Nobody can identify the bytes running in an environment	H.11.8 Delivery Traceability	H.11.2 Artifact Identity
Rollback does not restore the product	H.11.7 Delivery Recovery	H.11.4 Runtime Compatibility

For a first survey, read this page and the section entry articles. They expose the domain boundaries and item maps without requiring every detail. For a live problem, use Diagnose or search, read the one canonical item contract and its section orientation, then follow only the prerequisite or adjacent refs that the problem actually needs.

key takeaway

The Monorepo Handbook is a domain and symptom index for shared-repository work, not a linear Bazel level. Start from the boundary that owns your question, collect evidence appropriate to that domain, and use Bazel links only where its mechanisms implement the decision.