What does code ownership in a monolith actually mean?

In a monolith, every team can technically change every file, so ownership has to be a written agreement rather than a side effect of repository boundaries. It covers four responsibilities, not just approving pull requests:

  • Review: who must look at a change before it merges.
  • Routing: who receives bug reports, alerts and pages for the module.
  • Direction: who decides on design changes, public interfaces and deprecations.
  • Upkeep: who keeps dependencies current, tests reliable and dead code removed.

If you only define review, the other three default to whoever notices first. That usually means nobody, or the most senior engineer on call.

This checklist is for backend and platform engineers working in a single codebase shared by several teams. It pays off when three conditions overlap:

  • Several teams ship into the same deployable.
  • Changes regularly cross module lines.
  • Incidents get bounced around before anyone picks them up.

With one team or a rarely touched codebase, the overhead is not worth it.

Responsibility Owning team Contributor (non-owner) Platform team
Review changes Approves or rejects Proposes, addresses feedback Reviews build/tooling impact only
Bug reports and pages Primary recipient Reports, may assist Owns shared infrastructure alerts
Design and deprecation Decides, documents Raises proposals Advises on cross-cutting constraints
Dependencies and tests Maintains Keeps own changes green Provides tooling and upgrade paths

The core norm is that anyone may propose a change to any module, and the owners must respond within an agreed time, such as two working days. A response can be an approval, a rejection or a request for changes. That time limit is what keeps ownership from turning into gatekeeping.

How do you find out who really owns each part of the codebase?

Start from evidence rather than the org chart. The org chart shows how teams were meant to divide the work. Commit history shows how they actually divide it, and the gaps between the two are the areas you need to discuss.

For each top-level module, run git shortlog -sn --no-merges --since="12 months ago" -- path/to/module. This counts commits per author in that path, and mapping authors to their current teams gives a rough distribution for each area. git log --since="12 months ago" --name-only --format="" -- path/ lists the files touched in each commit. If you group those lists by commit, you can see which files usually change together. Files that keep changing together but sit in different directories, or belong to different intended teams, point to a boundary drawn in the wrong place. Put the results in a table next to your planned team boundaries and mark every module where the top contributor is not on the intended owning team.

Read the history with caution

History shows who changes code. It does not show who should own it, and the counts can mislead in two ways:

  • Heavy contributors may not be owners. A platform team running a dependency upgrade, or someone fixing bugs another team caused, can top the commit count for a module they have no wish to own.
  • Old commits reflect old teams. Commits from before a reorganisation belong to teams that no longer exist. Use a 6–12 month window so the data matches the current structure.

Use the results to start conversations with teams, not to assign ownership automatically.

#!/usr/bin/env bash
# Inventory who changes each module and which files change together.
set -euo pipefail

SINCE="12 months ago"   # short window so pre-reorg teams don't dominate
MODULES=(src/billing src/accounts src/notifications src/reporting)

# 1. Top authors per module, merges excluded.
#    HEAD is explicit: without a revision, shortlog reads stdin in scripts.
for mod in "${MODULES[@]}"; do
  echo "== $mod"
  git shortlog -sn --no-merges --since="$SINCE" HEAD -- "$mod" | head -n 5
done

# 2. File pairs that change in the same commit, most frequent first.
#    Commits touching more than 20 files are skipped: mass renames and
#    dependency upgrades say little about real coupling.
echo "== co-change pairs"
git log --no-merges --since="$SINCE" --name-only --format="--commit--" -- src/ |
awk '
  function flush(   i, j) {
    if (n > 1 && n <= 20)
      for (i = 0; i < n; i++)
        for (j = i + 1; j < n; j++)
          print files[i] "\t" files[j]
    n = 0
  }
  /^--commit--$/ { flush(); next }
  NF             { files[n++] = $0 }
  END            { flush() }
' | sort | uniq -c | sort -rn | head -n 30

# Next step: map authors to current teams by hand, then flag modules whose
# top contributor is not on the intended owning team, and pairs that cross
# module or team boundaries. Treat both as questions for the teams.

A shell script that lists the top committers per module over the last 12 months and ranks file pairs that are often committed together, so you can compare both against your intended team boundaries.

How should module boundaries follow team topology?

Start the draft from the business domain, not the directory tree. A stream-aligned team delivers a flow of change for one domain, such as checkout, catalogue or billing, so it should own the modules that change together when that domain changes. A platform team owns the shared infrastructure code that stream-aligned teams build on: persistence helpers, messaging, auth middleware, observability. This split lets most changes land inside one team's boundary, which keeps reviews local and releases independent.

+------------------+  +------------------+  +------------------+
| checkout/        |  | catalogue/       |  | billing/         |
| Team Checkout    |  | Team Catalogue   |  | Team Billing     |
+--------+---------+  +--------+---------+  +--------+---------+
         |  \                  |                  /  |
         |   +--> catalogue.api (public interface only)
         |                     |                     |
         v                     v                     v
+--------------------------------------------------------------+
| platform/  (db, messaging, auth, logging)   Team Platform    |
+--------------------------------------------------------------+

Allowed:   domain -> platform
           domain -> another domain's public API
Forbidden: platform -> domain
           domain -> another domain's internals

Dependencies point down and inward. Platform code that imports a domain module creates a cycle, and any change to that domain can then break every team.

Run a workshop with each team over the proposed map and compare it with the commit data you gathered. Look closely at any module that two teams edit together in most changes. That pattern means one of two things. The boundary may cut through a single concept, in which case you merge the module or split it along a different seam. Or the team split may not match how the work actually flows, in which case you move the responsibility to one team. Assigning co-owners usually hides the problem instead of fixing it.

 +----------------+    +------------------+    +----------------+
 | checkout/      |    | catalogue/       |    | billing/       |
 | Team Checkout  |    | Team Catalogue   |    | Team Billing   |
 | stream-aligned |    | stream-aligned   |    | stream-aligned |
 +-------+--------+    +------------------+    +--------+-------+
         +------------>| api/   (public)  |<------------+
         |             | internal/        |             |
         |             | (no outside use) |             |
         |             +--------+---------+             |
         |                      |                       |
         v                      v                       v
 +--------------------------------------------------------------+
 | platform/   db, messaging, auth, observability               |
 | Team Platform  (shared infrastructure)                       |
 +--------------------------------------------------------------+

 Allowed:    domain   --> platform
             domain   --> another domain's api/
 Forbidden:  platform --> any domain module
             domain   --> another domain's internal/
 Smell:      one module co-edited by two teams in most changes
             => merge the split concept, or redraw the team split

Stream-aligned teams own the checkout, catalogue and billing domain modules and depend downward on a platform layer owned by Team Platform. A domain may reach another domain only through its public api/, and a module that two teams co-edit signals a misplaced boundary.

How do you write a CODEOWNERS file that holds up?

Once the boundaries are settled, the CODEOWNERS file records them where tooling can act on them. Write it on purpose rather than letting it grow one pull request at a time.

Start with a catch-all default. Put a wildcard rule at the top that assigns every path to a default owner, such as a platform or architecture group. In common implementations, including GitHub's, the last matching pattern wins. That means a catch-all at the bottom would override everything above it, while one at the top acts only as a fallback. With the fallback in place, no new directory lands without an owner.

Prefer directory patterns over file lists. A rule for a module's directory keeps working when files are added, renamed or split. A list of individual files needs editing every time the module changes, and nobody notices when it falls out of date.

Assign teams, not people. A named engineer goes on leave, changes teams or leaves the company, and their paths quietly lose an owner.

Choice Benefit Cost
Fine-grained patterns Reviews route precisely Break silently when code moves
Coarse patterns Simple, rarely stale Reviews reach people without context
Individual owners Obvious who to ask Fragile when that person moves on
Group owners Resilient to turnover Only as accurate as current group membership

Group ownership moves the maintenance burden rather than removing it. Someone has to keep group membership current, or the file points to a team that no longer exists in practice.

# .github/CODEOWNERS
# Later matching patterns override earlier ones, so order matters:
# general rules first, more specific rules further down.

# 1. Catch-all fallback. It sits first so every rule below can override it.
#    Any new directory without its own rule still gets an owner.
*                         @example-org/platform-architecture

# 2. One rule per module directory, owned by a team rather than a person.
#    A trailing-slash directory pattern covers everything beneath it,
#    so added, renamed or split files stay covered.
/src/billing/             @example-org/billing-team
/src/accounts/            @example-org/identity-team
/src/notifications/       @example-org/messaging-team
/src/search/              @example-org/search-team

# 3. Shared code that needs review from two groups. Listing both teams
#    sends the review request to each of them.
/src/shared/money/        @example-org/billing-team @example-org/platform-architecture

# 4. Narrower overrides go after the module rule they refine. Placed above
#    /src/billing/, this line would be overridden and have no effect.
/src/billing/tax/         @example-org/tax-compliance-team

# 5. Build and CI configuration stays with the platform group, even when
#    the files sit inside a module directory.
/.github/workflows/       @example-org/platform-architecture
/src/**/Dockerfile        @example-org/platform-architecture

# Avoid long lists of individual files, such as:
#   /src/billing/invoice.py        @jane-doe
#   /src/billing/invoice_utils.py  @jane-doe
# These go stale without anyone noticing when files move or the person
# changes teams.

A GitHub-style CODEOWNERS file with a team-owned catch-all at the top, directory-level module rules below it, and narrower overrides placed last, because the last matching pattern wins.

How do you enforce ownership without creating review bottlenecks?

A CODEOWNERS file only routes review requests until you make owner approval mandatory. Turn on the branch protection setting that requires code-owner review on the main branch. Without it, the file decides who gets notified, and nothing more.

Review rules don't create module boundaries

Owner review controls who approves changes to a path. It does not stop the billing module from importing the internals of the orders module. That coupling slips through because no single diff looks like it crosses a boundary. Enforce boundaries in the build:

  • Restrict visibility. Use the language's tools, such as package-private types, internal packages or module export lists, so internals can't be reached from outside the module.
  • Give each module one public interface. Other modules may depend only on that interface. Owners can then review a small, stable surface instead of every file.
  • Ban illegal imports in CI. An architecture test makes the rule concrete. For example: "classes in orders.internal may only be imported by classes in orders." The build fails on a violation, so no reviewer has to catch it.

Keep cross-cutting changes moving

A repo-wide rename or dependency bump can touch dozens of owners. Without a plan, it waits on a dozen approvals. Set three rules:

  • Mechanical changes: a platform or release group may approve them alone if CI passes.
  • Generated code: owners review the generator and its input, not the generated files.
  • Large refactors: announce them ahead of time and land them in small batches.

Avoid bottlenecks and gatekeeping

Every owning group needs at least two reviewers, preferably in different time zones. Publish a review-time expectation and a fallback approver for when it is missed. Owners can make reasonable change requests, but they can't refuse a correct change because they would have built it differently. If that keeps happening, escalate it like any other ownership dispute.

// Architecture test (ArchUnit + JUnit 5). Runs in CI like any other test,
// so a boundary violation fails the build before a reviewer ever sees it.
package com.example.architecture;

import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;

// Scan production code only; test helpers may reach into internals.
@AnalyzeClasses(
    packages = "com.example",
    importOptions = ImportOption.DoNotIncludeTests.class)
class ModuleBoundaryTest {

    // Only the orders module may touch its own internals.
    @ArchTest
    static final ArchRule ordersInternalsStayInsideOrders =
        noClasses().that().resideOutsideOfPackage("com.example.orders..")
            .should().dependOnClassesThat()
            .resideInAPackage("com.example.orders.internal..")
            .because("other modules must use com.example.orders.api");

    // Same rule for billing. Add one rule per module, or generate
    // the rules from a list of module names as the codebase grows.
    @ArchTest
    static final ArchRule billingInternalsStayInsideBilling =
        noClasses().that().resideOutsideOfPackage("com.example.billing..")
            .should().dependOnClassesThat()
            .resideInAPackage("com.example.billing.internal..")
            .because("other modules must use com.example.billing.api");
}

An ArchUnit test that fails the build when code outside a module depends on that module's internal package. This leaves each module's api package as the only surface other modules can use.

How do you handle shared, orphaned and operational ownership?

Shared code still needs a named steward. Libraries, utilities, config, schemas and build files tend to collect broad patterns or fall through to the catch-all rule, and a catch-all assigned to the platform team turns that team into the reviewer of last resort for everything nobody wanted. Give each shared area an explicit owner, even when many teams contribute. The steward does not write most of the changes. It keeps the API coherent, decides on deprecations and answers questions. For schemas and build files, which affect every team, the steward is the group that understands the blast radius, and other teams still make routine edits.

Keep the default rule narrow and visible. Count how many paths fall through to it, and treat any increase as work to be assigned to a real owner.

Reorgs and dissolved teams

Ownership moves with the reorg, not after it. When a team is split, merged or dissolved, update the map in the same change that updates the team structure, with every path assigned to a receiving team. Run a scheduled check that flags owner groups that no longer exist, have no active members or have only one member. These paths look owned in review but have no one to answer for them.

Ownership outside review

Generate service and module owner tags from the same map and attach them to logs, alerts, error reports and on-call routing. When an exception is raised in a module, it should page the team that would approve a fix to that module. If you keep a separate list, it will drift from the map within a few reorgs.

When should you avoid strict ownership, and what are the alternatives?

Strict mapping pays off only when ownership is stable enough to write down. It is overkill for a team of five or six engineers who already review each other's work and share on-call. It also fits poorly in a codebase in heavy flux, where module boundaries move every few weeks and each refactor turns into an ownership-file edit. Organizations that reorganize every few quarters have a different problem: the map goes stale faster than anyone maintains it.

A stale map is worse than none. Without a map, people ask around and find the right person. With a wrong map, reviews and alerts go to a team that no longer knows the code. Everyone involved assumes the work is covered, so nobody checks.

Approach Setup effort Ongoing upkeep Review latency Fits when
Collective ownership None None Lowest Small team with shared context
Coarse directory-level ownership Low Low Low A few teams working in loosely separated areas
Strict CODEOWNERS plus structural boundaries Medium to high: boundary checks and module refactors Revised at every reorg Higher, and depends on owner availability Many teams with stable domains
Extracting services High High: deploys, API contracts, operations Low inside a service, slow for cross-service changes Boundaries are proven and need independent deploys or scaling

The return on strict ownership shows up in three places:

  • Incident routing: incidents page the right team first instead of bouncing through a triage channel.
  • Code review: reviews stop landing on people who approve changes they don't understand.
  • Deprecation: someone has the authority to decide that old code gets deleted.

If none of these cause problems today, start with coarse ownership and tighten it only in the areas where they do.

Phased checklist: keeping the ownership map a living artifact

Ownership maps decay quietly, so treat this as a sequence you repeat, not a one-time project.

Phases

  1. Define responsibilities. Write down what an owner is accountable for (review, incidents, dependency upgrades, deprecation) before naming anyone. Otherwise teams accept paths without knowing the cost.
  2. Inventory and analyze history. Compare commit and review history against the org chart. Where they disagree, the history usually reflects who actually does the work.
  3. Draft boundaries with teams. Circulate the proposed map and let teams contest it. Ownership that is imposed tends to be ignored.
  4. Write CODEOWNERS with a default owner. A catch-all entry at the top means every path routes to someone. More specific rules below it override the default.
  5. Enable enforcement. Require owner approval only after the map has been stable for a few weeks, so early mistakes don't block merges.
  6. Add structural checks. In CI, validate CODEOWNERS syntax, confirm every referenced team exists, and fail when new top-level paths match only the default rule.
  7. Connect to operational routing. Use the same mapping for alerts, error triage, and on-call so review ownership and incident ownership don't drift apart.
  8. Schedule recurring review. Review quarterly and at every reorg. Reorgs are when the map goes stale fastest.

Signals to track

  • Unowned paths: files that only the default rule covers.
  • Over-shared paths: paths with too many owner teams, which usually means nobody owns them.
  • Inactive owner groups: teams that have no recent reviews or members who have left.
  • Review latency per owner group: a sustained rise points to a bottleneck or an overloaded team.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to code ownership monolith, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.