Why this matters
As a Platform Engineer, you’ll design CI/CD flows that keep teams shipping safely and quickly. Choosing between a monorepo and a multi-repo model—and operating them well—directly affects developer experience, build speed, release safety, and compliance.
- Support hundreds of services without blowing up build times.
- Enforce ownership and security boundaries at scale.
- Coordinate cross-repo releases without manual spreadsheets.
- Enable incremental builds and test selection to reduce feedback time.
Concept explained simply
Monorepo: many components share one repository. Multi-repo: each component lives in its own repository.
- Monorepo strengths: unified standards, easy refactors, shared tooling, simpler dependency visibility.
- Monorepo risks: naive pipelines rebuild too much; permissions and ownership need careful rules; repo tools must scale.
- Multi-repo strengths: clear boundaries, separate lifecycles, simpler permissions per team, smaller clone size.
- Multi-repo risks: dependency drift, duplicated tooling, complex cross-repo changes and release orchestration.
When in doubt
If teams often change code across components in one change, monorepo may help. If strict isolation or different regulatory scopes are required, multi-repo usually fits better.
Mental model
Think in graphs and diffs:
- Dependency graph: nodes are packages/services; edges show what depends on what.
- Change set: files touched by a PR.
- Affected set: nodes that changed or depend on changed nodes.
- Pipeline plan: only build/test/deploy the affected set, reuse caches for the rest.
Whether mono or multi, the pipeline should compute the affected set and then run the smallest safe workflow.
Worked examples
Example 1: Monorepo with shared libraries
Repo contains apps A, B and libraries lib-core, lib-ui. A depends on lib-core and lib-ui; B depends on lib-core.
- PR modifies lib-ui only.
- Compute affected: lib-ui → A (depends); B unaffected.
- Pipeline runs: build+test lib-ui and A only; reuse cached artifacts for B.
Sample pipeline sketch
jobs:
detect_changes:
steps:
- run: echo "Compute affected graph from changes..."
build:
needs: detect_changes
strategy: matrix over [lib-ui, A]
test:
needs: build
strategy: matrix over [lib-ui, A]
Example 2: Multi-repo microservices with shared contracts
Repos: svc-orders, svc-payments, proto-contracts. A change in proto-contracts may break both services.
- PR to proto-contracts merges to main with a new tag v1.8.0.
- Contracts CI publishes artifact and triggers downstream pipelines in both services.
- Each service runs contract tests; only if green, deploy continues.
Triggering pattern
- Use artifact tag as the contract version input to downstream jobs.
- Record a release manifest listing repos and their SHAs for traceability.
Example 3: Hybrid approach (mono for libs, multi for services)
Shared libraries live in a monorepo; services live in separate repos.
- Library changes publish versioned packages.
- Services specify semantic version ranges; Renovation job creates update PRs which run tests and deployments.
Benefits
- Centralized shared code velocity with monorepo tooling.
- Service isolation and simpler permissions in multi-repos.
Implementation patterns in CI/CD
1) Dependency graph + affected targets
- Maintain a graph (workspace file, build system, or generated).
- On each PR, compute changed files → affected nodes.
- Execute jobs only for affected nodes; cache the rest.
2) Caching and remote build cache
- Key caches by dependency lockfiles and source checksums.
- For monorepos, use a shared remote cache to avoid rebuilding identical targets.
3) Ownership and review rules
- Use code ownership files to map paths → teams.
- Require approvals from owners for sensitive areas.
4) Versioning and releases
- Monorepo: independent package versions or single version—pick one and stick to it.
- Multi-repo: tag each repo and generate a release manifest (repo, tag, commit SHA).
5) Git strategies
- Trunk-based with short-lived branches and required checks.
- Automated merges after green builds; avoid long-lived release branches unless needed.
6) Deployment orchestration
- Use an orchestrator pipeline to fan out to services.
- Support canary or blue/green rollouts per service; roll back independently.
Security and compliance
- Permissions: in monorepos, restrict paths; in multi-repos, restrict repos.
- Secrets: scope narrowly per job; avoid broad environment secrets.
- Auditability: store release manifests and build provenance (who built what from which commit).
- Policy: enforce security scans as required checks before merge.
Operational tips
- Scale runners elastically; prefer containers with warm caches.
- Shard tests by historical timing to balance parallel jobs.
- Prune artifact retention; keep only what’s needed for rollback and traceability.
- Measure: time-to-first-failure, cache hit rate, and PR lead time.
Exercises
These mirror the exercises below. Do them in order; each builds intuition for mono vs multi flows.
- Exercise 1: Compute the affected build set in a monorepo change.
- Exercise 2: Plan a cross-repo coordinated release with a manifest.
Checklist before you start
- List components and direct dependencies.
- Decide versioning approach (independent or single for mono; per-repo for multi).
- Define what triggers downstream builds.
- Write how you will record release provenance.
About the Quick Test and progress
The Quick Test is available to everyone. Only logged-in users will have their results and progress saved.
Common mistakes and self-check
- Rebuilding everything on every PR in a monorepo. Self-check: does your pipeline compute an affected set?
- No clear ownership rules. Self-check: are reviewers auto-requested based on path rules?
- Orchestrating multi-repo releases by chat. Self-check: do you produce a machine-readable release manifest?
- Over-permissive secrets. Self-check: can each job access only what it must?
- Ignoring rollback. Self-check: can you redeploy last known good versions per service quickly?
Practical projects
- Monorepo POC: 5 packages with a simple dependency graph; implement affected-only builds and tests with a shared cache.
- Multi-repo Orchestrator: 3 small services + 1 contracts repo; implement contract publish → fan-out builds → green deploys.
- Release Manifest: create and store a JSON manifest for a cross-repo release (repo, tag, SHA, artifact digest) and print it in a summary step.
Mini challenge
Your company has 15 services, frequent cross-service refactors, and strict separation for billing. Propose a hybrid structure and a CI/CD plan that supports fast refactors while keeping billing isolated. Write 5–7 bullet points: repo layout, dependency management, affected builds, release orchestration, and rollback.
Who this is for
- Platform Engineers designing CI/CD at scale.
- Backend Engineers contributing to shared libraries and many services.
- Tech Leads owning release safety and developer velocity.
Prerequisites
- Comfort with Git branching and pull requests.
- Basic CI/CD concepts: builds, tests, artifacts, deployments.
- Familiarity with one build tool (e.g., language-specific) and containerization basics.
Learning path
- Understand repo models and dependency graphs.
- Implement affected-only builds and shared caches.
- Add ownership rules, required checks, and policy gates.
- Design versioning and release strategies (mono and multi).
- Build an orchestrator pipeline and a release manifest.
Next steps
- Complete the exercises and take the Quick Test.
- Apply the patterns to a small internal repo or a sandbox.
- Measure pipeline improvements: PR lead time and cache hit rate.