CONCEPT Cited by 1 source
Polyrepo shared build logic¶
Definition¶
The cross-cutting concern an organization with many independent source repositories (vs a single monorepo) has to solve: how do tens of thousands of repos share build conventions, dependency policies, plugin configurations, and rule enforcement without the "refactor everyone at once" affordance a monorepo provides?
The wiki's first canonical instance is Netflix's JVM Ecosystem team's Nebula plugin suite, which provides the substrate on top of which Netflix builds Nebula ArchRules and other paved-road build tools.
The Netflix framing¶
"At Netflix, we operate using a polyrepo strategy with tens of thousands of Java repositories. This means that we need to have ways of sharing common build logic across these repositories. On the JVM Ecosystem team within Java Platform, we build tooling such as the Nebula suite of Gradle plugins to provide standard ways to build projects, keep dependencies up-to-date, and publish artifacts reliably across the Java ecosystem. Our mission also entails providing build-time feedback to the developer when they deviate from the paved road, or when their code base contains technical debt." — sources/2026-05-08-netflix-scaling-archunit-with-nebula-archrules
Three responsibilities named:
- Standard ways to build — opinionated Gradle plugins + wrapper that every repo inherits.
- Keep dependencies up-to-date — automated bump tooling (analog to Dependabot but org-internal).
- Publish artifacts reliably — consistent publication metadata + Module Metadata everywhere.
Plus a fourth responsibility added in the ArchRules post:
- Build-time feedback for paved-road deviations and tech debt — ArchRules running in every CI build with dashboard aggregation in the Internal Developer Portal.
Why polyrepo + shared build logic vs monorepo¶
The post doesn't justify the polyrepo choice — it takes it as given. Industry context:
| Aspect | Monorepo | Polyrepo + shared build logic |
|---|---|---|
| Refactor multiple consumers at once | Single PR | Many coordinated PRs |
| Library deprecation removal | Atomic | Requires consumer-by-consumer migration |
| Build-tool consistency | Trivial (one config) | Requires deliberate tooling |
| Per-team autonomy | Constrained by shared config | High |
| CI infrastructure cost | One CI for all | Per-repo CI |
| Onboarding | Whole-codebase exposure | Repo-scoped |
| Versioning | All-at-once | Per-library independent |
Netflix's polyrepo choice prioritizes per-team autonomy + independent versioning at the cost of needing tooling like Nebula to recreate consistency.
Counter: monorepo orgs at scale¶
The other end of the spectrum:
- Google — single monorepo (
google3), Bazel build - Meta — single monorepo (Buck2 build)
- Twitter (now X) — Bazel-based monorepo
These orgs solve the "refactor everyone at once" problem trivially but face their own scale issues (massive single-repo build/test farms, code-search tooling, code review at billion- line scale).
The substrate stack¶
Netflix's polyrepo-shared-build-logic substrate, per the post + public Nebula docs:
- Gradle as the build tool (every JVM repo).
- Standard Gradle wrapper with version locked across the fleet — "Our internal Nebula standard Gradle wrapper and plugin suite automatically enable the ArchRules runner on every project."
- Nebula plugin suite (github.com/nebula-plugins) — opinionated layer on top of Gradle for build standardization, dependency hygiene, publication conventions.
- Gradle Module Metadata for variant-publication (load-bearing for ArchRules' classifier- variant mechanism).
- Internal Developer Portal — dashboard aggregation for per-repo signals (the post mentions it as ArchRules' reporting destination but doesn't expand).
Tradeoffs the substrate has to address¶
- Plugin upgrade rollout — pushing a new plugin version across 5,000+ repos requires the wrapper-version-pin mechanism to take effect (Gradle wrapper auto-update) without breaking builds.
- Cross-cutting rule enforcement — solved by Nebula ArchRules.
- Dependency policy — Nebula ships dependency-resolution rules (e.g. force-versioning, conflict-resolution heuristics) ensuring all repos resolve the same library version where cross-team consistency matters.
- API deprecation — solved by the ArchRules-as-cross-repo-impact-discovery pattern (see patterns/static-analysis-as-cross-repo-impact-discovery).
Adjacent concepts¶
- concepts/architectural-fitness-function — what ArchRules enforces.
- concepts/blast-radius-multiplier-at-fleet-scale — the related concern about how a single change can cascade across a polyrepo fleet.
Seen in¶
- sources/2026-05-08-netflix-scaling-archunit-with-nebula-archrules — Netflix's tens-of-thousands-of-Java-repos fleet served by the Nebula plugin suite + ArchRules layer.