Skip to content

PATTERN Cited by 1 source

Centralized fleet-wide rule catalog

Definition

A polyrepo organization runs one canonical rule-execution plugin in every CI build of every repo in the fleet, with rules sourced from a central catalog that includes both standalone (cross-cutting) rules and library-bundled (scoped) rules. Rule violations stream to a central dashboard in the org's Internal Developer Portal. The shape allows hundreds of rules to enforce architectural intent across thousands of repos without per-repo configuration overhead.

The wiki's first canonical instance is Netflix's Nebula ArchRules deployment: 358+ rules × 5,000+ repos × ~1M issues as of 2026-05.

When to use

You're operating in a polyrepo environment where:

  • Many independent repos (hundreds to tens of thousands).
  • Cross-cutting architectural concerns require enforcement (deprecated-API detection, security-rule violations, naming conventions, layering).
  • Per-repo rule-by-rule configuration is infeasible — you need a default-on enforcement mechanism.
  • Library authors need visibility into which downstream consumers depend on which API surfaces.

If you have a monorepo, this pattern is overkill — monorepo-wide CI can run rules over the whole codebase in one go.

The pattern

Canonical Gradle wrapper enables the runner by default

"Our internal Nebula standard Gradle wrapper and plugin suite automatically enable the ArchRules runner on every project." — sources/2026-05-08-netflix-scaling-archunit-with-nebula-archrules

The org maintains a standard build-tool wrapper (Gradle wrapper in Netflix's case). Every repo inherits the wrapper. The wrapper auto-applies the rule-runner plugin. No per-repo opt-in required.

Rules come from two sources

  1. Standalone rule libraries — rules-only artifacts covering cross-cutting concerns (Nullability, Security, Joda/Guava-discouragement, Gradle-plugin-best-practices). Consumers add these explicitly: 
    dependencies { archRules("com.netflix:standalone-rules:1.0.0") }
    Or the canonical wrapper auto-applies common ones.
  2. Bundled rules — co-located with libraries, auto-scoped to consumers. See patterns/bundled-rules-auto-scoped-to-library-consumers.

Per-CI-build execution

Every main-branch CI build runs the rules. Output:

  • Build-failure for high-priority rules (configurable failure-threshold).
  • Reports for everything else — JSON + console + binary- serialized for custom reporters.

Dashboard aggregation

"[The Nebula plugin suite] provides a custom reporter which sends the report data to our Internal Developer Portal on every main-branch CI build." — sources/2026-05-08-netflix-scaling-archunit-with-nebula-archrules

The custom reporter ships per-rule violation data to a central service (Internal Developer Portal). Operators query the dashboard:

  • "Which repos still call LegacyService.oldMethod?"
  • "What's the trend on Joda-Time usage across the fleet?"
  • "Which rules have the most violations? The most repos affected?"

This reverses the discovery direction: instead of going repo-by-repo asking "do they violate any rules?", you go rule-by-rule asking "which repos violate this rule?".

Operational scale (Netflix as canonical instance)

"We are now running 358 (and counting) rules across over 5,000 repositories detecting over nearly 1 million issues. About 1,000 of these issues are for 'High' priority rules. Being able to run these rules on this scale allows us to quickly gain insight into our large fleet of microservices, and identify the areas carrying the most critical technical debt. This makes it easier to focus and prioritize our efforts." — sources/2026-05-08-netflix-scaling-archunit-with-nebula-archrules

Derived numbers:

  • ~200 issues per repo on average (1M / 5,000).
  • ~0.1% high-priority rate (1,000 / 1,000,000).
  • Per-rule fan-out highly skewed (some rules fire in many repos, others in few).

The dashboard is the central operator-facing surface; without it, 1M issues is unactionable noise.

Distinct from per-repo lint

Per-repo lint (e.g. local-only ESLint, language-specific formatters):

  • Configured per-repo.
  • Rules are repo-local.
  • No central visibility.

Centralized fleet-wide rule catalog:

  • Configured org-wide via the canonical wrapper.
  • Rules are org-shared (standalone) or library-shared (bundled).
  • Central dashboard visibility.

The two coexist — per-repo lint catches stylistic issues local to one team's preferences; the fleet-wide catalog catches architectural / API-surface / security issues that matter across the org.

Rollout discipline

Adding a new high-priority rule to the central catalog can fire across many repos simultaneously. Netflix's framing implies a measure-then-enforce discipline:

  1. Ship rule at Medium or Low priority initially.
  2. Read dashboard; identify repos with violations.
  3. Coordinate cleanup with affected teams.
  4. Promote to High priority (build-failing) once cleanup is done.

The post doesn't make this discipline explicit but implies it via the "about 1,000 of these issues are for 'High' priority rules" split (vs ~999,000 non-high-priority).

Adjacent patterns

Hard problems

  • Plugin upgrade rollout — a new plugin version is rolled out via Gradle wrapper version pin. Repos that haven't picked up the latest wrapper are stuck on old rules. The org needs a wrapper-update enforcement mechanism.
  • Build time overhead — every CI build runs every rule. At scale this is meaningful. Bundled-rule auto-scoping helps bound the per-repo cost; standalone rules don't auto-scope.
  • Dashboard staleness — repos with infrequent CI builds have stale dashboard entries.
  • Rule authorship gating — who decides a new rule joins the central catalog? Without governance, the catalog can balloon.
  • High-priority-rule social cost — when shipping a new high-priority rule, the library author / catalog owner needs to coordinate cleanup across affected teams. The pattern doesn't dictate how.

Seen in

Last updated · 542 distilled / 1,571 read