Repository Architecture & Monorepo Strategy

This decision shapes your CI architecture, dependency management, code-sharing patterns, team autonomy, and on-call blast radius for years. There's no universally correct answer — but there is a decision framework that cuts through the religion around it.

The core trade-off

Decision framework

Answer these four questions:

1. Do services share code that changes together? If yes, and that shared code is a non-trivial library that consumers need to update in lockstep, monorepo wins. If the shared code is stable and versioned independently (like an npm package), polyrepo is fine.
2. How many teams, and how independent are they? Two teams sharing a monorepo with clear CODEOWNERS is fine. Twenty teams with conflicting release cycles and different tech stacks is a recipe for monorepo pain.
3. What's your CI build time budget? Monorepo only works at scale if you can detect and run only the affected projects. If you're not willing to invest in that tooling, polyrepo keeps CI fast by default.
4. How often do cross-service changes happen? If two services always change together, they should be in one repo. If they almost never change together, separate repos reduce noise.

The hybrid (most pragmatic for growing teams)

Group services that genuinely evolve together into a monorepo per domain, keep truly independent services in their own repos. Example:

Two GitHub features make monorepos tractable: CODEOWNERS for ownership and required reviews, and path filters in Actions for targeted CI.

CODEOWNERS

The CODEOWNERS file lives in the repo root, .github/, or docs/. It maps file paths to GitHub users or teams using gitignore-style patterns. When a PR changes a file, the matching owners are automatically added as required reviewers (if branch protection requires CODEOWNER approval).

Pattern precedence: the last matching pattern wins. Put general patterns first, specific ones last. A file matched by * and then /services/auth/ is owned by @acme/security-team, not the default owner.

Path-filtered Actions for monorepo CI

Without path filters, every push to any file triggers all workflows — CI costs explode and developer feedback slows. Use paths and paths-ignore to scope each workflow:

Affected-service detection with dynamic matrices

For complex monorepos, compute the affected services at runtime rather than maintaining one workflow per service:

A repository marked as a template lets anyone in your org create a new repo pre-populated with its files. This is the right way to standardise new service scaffolding — not manually copying from a reference repo.

What a template copies — and what it doesn't

The missing pieces — secrets, branch protection rules, team access — need to be wired up separately. Use a GitHub App + Actions workflow triggered on repository: created to automate this:

What to put in an org template

This comes up whenever a team wants to share code between repos. All three options work; all three have costs. The honest comparison:

Submodule quick reference

GitHub shipped Repository Rulesets in 2023 as the next-generation replacement for Branch Protection Rules. Both still exist; understanding which to use and how to migrate matters for tech leads managing org-wide policy.

Key differences

Creating a ruleset via the UI

Settings → Rules → Rulesets → New ruleset → New branch ruleset

1. Name: protect-main
2. Enforcement: Active
3. Bypass list: add your release automation GitHub App (so it can push tags without a PR)
4. Target branches: include refs/heads/main and refs/heads/release/**
5. Rules: restrict deletions, block force pushes, require PR with 1 approving review, require status checks to pass

At 50+ repos, inconsistent naming makes discoverability, automation, and access management painful. Establish conventions early; they compound in value.

Repository naming

Visibility policy

• Internal (GitHub Enterprise): visible to all org members, not the public. Default for most product code — balances discoverability with security.
• Private: explicitly scoped access. Use for repos containing credentials, sensitive customer data processing, or unreleased product features.
• Public: requires a deliberate decision + security review. Enables Dependabot on public repos for free, but exposes your code, commit history, and any accidentally committed secrets permanently.

Archiving strategy

Archived repos are read-only and hidden from the default org repo list. Archive when:

• A service is fully decommissioned but the code is valuable as reference
• An experiment or spike was completed and won't be resumed
• A library has been superseded and all consumers have migrated

Before archiving: ensure runbook links in incident management tools, internal wikis, and Slack bookmarks are updated to point to the archive or the successor.

GitHub surfaces these files at specific URL paths and in the UI. Each one has an automation hook beyond its human-readable purpose.

Minimal SECURITY.md template

Default branch naming

GitHub now defaults new repos to main. Set the org-level default under Organization Settings → Member privileges → Repository default branch. This affects new repos; existing repos with master need a manual rename:

.github/ directory layout

The .github/ directory is the convention for everything GitHub-specific. A complete layout:

The org-level .github repository

Create a repository named exactly .github inside your GitHub organization. Files placed here become org-wide defaults — they apply to any repo in the org that doesn't have its own version of the file. This is the single most leveraged thing you can do for org-level standardisation.

Workflow templates (workflow-templates/)

Files in .github/workflow-templates/ appear as suggestions in the Actions → New workflow tab of every repo in your org. Pair each .yml with a .properties.json:

When a developer in your org opens the Actions tab and clicks "New workflow," your template appears prominently alongside GitHub's built-in ones. This is the lowest-friction way to nudge teams toward org standards without forcing it.