Code Ownership Policy Template (CODEOWNERS)

Code Ownership Policy: [Organisation or product name]

Policy for who owns which code and what owning it means: ownership model and principles, roles and responsibilities, numbered policy statements, the CODEOWNERS file standard, review duties and service levels, escalation, orphaned code and ownership transfers, alignment with the service catalogue, exceptions, compliance measurement and review. Aligned with the code owner features documented by GitHub (About code owners) and GitLab (Code Owners), and with the SLSA specification v1.2 Source track, whose Level 4 requires two trusted people to review changes to protected branches. Replace every [bracketed] value and every row marked Example. Worked examples use Corvid Commerce, a fictional SaaS company that runs an online checkout platform.

Document control

Approvals

Revision history

Contents

1. Purpose and scope
2. Ownership model and principles
3. Roles and responsibilities
4. Policy statements
5. CODEOWNERS file standard
6. Review duties and service levels
7. Escalation and disputes
8. Orphaned code and ownership transfers
9. Service catalogue alignment
10. Exceptions
11. Compliance measurement
12. Review cycle and related documents
13. Glossary and references

1. Purpose and scope

1.1 Purpose

This policy makes sure that every piece of production code, configuration and pipeline definition at [Organisation] has an accountable team that reviews changes to it, keeps it healthy and answers for it during incidents. It also defines how ownership is recorded in machine-readable form so that the source platform can route reviews and enforce approval.

1.2 Scope

1.3 Outcomes sought

1. Every change to protected branches is reviewed by someone who knows the affected code.
2. Review requests reach the right team automatically, without the author guessing.
3. Security-sensitive paths always get specialist review, enforced by a platform rule rather than by convention.
4. Incidents, vulnerability reports and dependency alerts reach an owner within hours.
5. No production code is left without an owner after reorganisations or departures.

2. Ownership model and principles

2.1 Ownership models

Example: Corvid Commerce uses weak ownership by default. Strong ownership applies to payments/crypto/ and the signing configuration. Collective ownership applies to docs/ and examples/.

2.2 Principles

1. Teams own, people serve. Owners are teams; individuals act for their team.
2. Ownership follows the service. The team that runs a service in production owns its code, its pipeline configuration and its alerts.
3. Ownership is duty, not just approval. Owners review, maintain, upgrade dependencies, fix vulnerabilities and answer incidents.
4. Contributions are welcome. Owners help other teams land changes; they do not reject work only because another team wrote it.
5. Ownership is visible and current. Ownership data lives in files and catalogues that the platform reads, and it is checked continuously.

3. Roles and responsibilities

3.1 Roles

3.2 RACI

R = responsible, A = accountable, C = consulted, I = informed.

4. Policy statements

The key words MUST, MUST NOT, SHOULD and MAY are used as requirement levels in this section.

5. CODEOWNERS file standard

5.1 Location and format

1. Place the file at .github/CODEOWNERS on GitHub or .gitlab/CODEOWNERS on GitLab, and keep only one copy per repository. Both platforms search several locations and use the first file they find, so a stray second copy causes confusion.
2. Keep the file on every protected branch. GitHub reads the file from the base branch of the pull request, so a release branch uses its own copy.
3. Order rules from general to specific. On GitHub, and within each section on GitLab, the last matching pattern for a path decides its owners, so the catch-all * rule comes first. GitLab combines the owners of every section that matches a path.
4. Put all owners of one pattern on one line. Separate lines for the same pattern do not combine; only the last one applies.
5. Do not treat a line with several owners as a demand for several approvals. On GitHub, when code owner review is required, an approval from any one owner listed for the path satisfies it. Use the mechanisms in section 5.3 when a second team's approval must be mandatory.
6. Group rules under comment headings by component, and keep each line short enough to review.
7. Do not rely on syntax that the platform ignores. GitHub patterns follow most .gitignore rules but do not support ! negation, [ ] character ranges or escaping a leading #; paths are case sensitive. Lines with invalid syntax are skipped, so validate the file in CI.
8. Keep the file under the platform size limit. GitHub does not load a CODEOWNERS file of 3 MB or more; large monorepos split ownership by directory patterns rather than listing files.

5.2 Example file

Example: CODEOWNERS for the Corvid Commerce checkout monorepo.

# Default owner: every file must match at least one rule (OWN-POL-002)
*                               @corvid/checkout-team

# Services
/services/cart/                 @corvid/checkout-team
/services/payments/             @corvid/payments-team
/services/payments/crypto/      @corvid/payments-team @corvid/appsec
/services/catalog/              @corvid/catalog-team
/web/storefront/                @corvid/web-team

# Migrations: request review from both teams; DBA approval is made
# mandatory by the ruleset required-reviewer rule in 5.3, not by this file
/services/cart/migrations/      @corvid/checkout-team @corvid/dba
/services/payments/migrations/  @corvid/payments-team @corvid/dba

# Security-sensitive paths (OWN-POL-007); AppSec approval is mandatory
# through the required-reviewer rule, this file only requests it
/services/auth/                 @corvid/identity-team @corvid/appsec
/web/storefront/security-headers.ts  @corvid/web-team @corvid/appsec

# Pipeline, deploy and governance files (OWN-POL-006)
/.github/                       @corvid/platform-team @corvid/checkout-team
/.ci/                           @corvid/platform-team @corvid/checkout-team
/deploy/                        @corvid/platform-team @corvid/sre @corvid/checkout-team
/.github/CODEOWNERS             @corvid/platform-team @corvid/engineering-leads @corvid/checkout-team

# Collective ownership: any member with write access may approve
/docs/
/examples/

In the example, the migration rules appear after the service rules and repeat the service team, so review is requested from the service team and the database team together. Because the last matching pattern replaces earlier owners rather than adding to them, a migration rule that listed only @corvid/dba would remove the service team, and one placed above the service rules would be overridden and drop the database team. The pipeline and deploy rules repeat @corvid/checkout-team for the same reason (OWN-POL-006). The paths /docs/ and /examples/ have no owner on purpose; on GitHub a path with no owner can be approved by anyone with write access.

Listing two teams on one line requests review from both, but on GitHub an approval from any one listed owner satisfies code owner review, so the checkout team alone could approve a migration. The file therefore routes reviews, and a separate rule makes the specialist approval mandatory:

• GitHub: add the ruleset rule for required reviewers (under "Require a pull request before merging"; generally available since February 2026). Each entry names a team, a file pattern and the number of approvals that team must give. Example: @corvid/dba with 1 approval on services/*/migrations/**; @corvid/appsec with 1 approval on services/payments/crypto/**, services/auth/** and web/storefront/security-headers.ts; @corvid/platform-team with 1 approval on .github/**, .ci/** and deploy/**. Only approvals from team members with write access count.
• GitLab: put each specialist path in its own section. Every required section that matches a changed file needs its own approval, so the service team and the specialist both approve.

# GitLab equivalent (Premium or Ultimate): one section per mandatory approver
[Checkout] @corvid/checkout-team
/services/cart/

[Database] @corvid/dba
/services/cart/migrations/
/services/payments/migrations/

[Security][1] @corvid/appsec
/services/payments/crypto/
/services/auth/

5.3 Platform behaviour to know

5.4 Validation

The platform team runs a CODEOWNERS check on every pull request and nightly:

1. File present in the agreed location and below the size limit.
2. No syntax errors reported by the platform's CODEOWNERS error view or API.
3. Every file matched by at least one rule (OWN-POL-002).
4. Every owner is a team that exists, is visible and has write access (OWN-POL-003, OWN-POL-004).
5. Required specialist owners present on sensitive path patterns, and a matching required-reviewer rule or required section exists for each (OWN-POL-006, OWN-POL-007).
6. Owners agree with the service catalogue (OWN-POL-012).

6. Review duties and service levels

6.1 What an owner review covers

1. Correctness and design fit with the component.
2. Tests: new behaviour is tested and existing tests still make sense.
3. Operability: logging, metrics, alerts and runbooks are updated when behaviour changes.
4. Security and privacy: no new secrets, injection paths or unreviewed data flows; escalate to the specialist owner when unsure.
5. Compatibility: API, schema and configuration changes follow the expand and contract approach.
6. Size: changes that are too large to review well are sent back for splitting.

6.2 Service levels

Working hours are those of the owning team's home time zone. Teams that span regions keep a rota so that one region covers each working day.

6.3 Review rota

Example: The payments team assigns two reviewers per week through the platform's automatic team review assignment. Requests go to the rota, not to the whole team, which keeps notification noise low. When both rota members are absent, the engineering manager reassigns within [4 working hours].

7. Escalation and disputes

7.1 Late reviews

1. After the decision service level passes, the author posts in the owning team's channel and tags the rota.
2. After a further [1 working day], the author escalates to the owning team's engineering manager, who assigns a reviewer.
3. Repeated breaches are reported monthly (section 11) and discussed in the engineering leads meeting.
4. Administrators MUST NOT bypass code owner review to resolve a late review. Emergency changes follow Branching Strategy (dev/branching-strategy) section 10.

7.2 Disputes

Record design decisions that settle a dispute in Architecture Decision Record (dev/adr).

8. Orphaned code and ownership transfers

8.1 Detection

Code is orphaned when any of these hold: its owning team no longer exists, the team has no members, the team has write access removed, the component has no entry in the service catalogue, or the team has declined ownership in writing. The nightly validation job lists orphaned paths and opens a ticket per component.

8.2 Orphaned code register

8.3 Transfer checklist

1. Agree the transfer between both engineering managers and record it in the ticket.
2. Hand over: architecture overview, runbooks, open incidents, open vulnerabilities, dependency backlog, known technical debt from Technical Debt Register (architecture/tech-debt-register).
3. Move the CODEOWNERS entries and the service catalogue entry in the same change.
4. Move on-call schedules, alert routing and vulnerability queues to the receiving team.
5. Give the receiving team write access and remove access no longer needed.
6. The receiving team confirms acceptance in writing; until then the sending team stays the owner.

8.4 Transfer worked example

Example: When the payments team split into payments-core and payments-risk, 14 paths moved. The transfer took 6 working days: CODEOWNERS and catalogue updated on day 1, alert routing on day 2, two runbook walkthroughs on days 3 and 4, and the vulnerability queue (5 open findings) on day 5. Payments-risk confirmed acceptance on day 6, within the OWN-POL-010 limit.

9. Service catalogue alignment

New services created from Platform Golden Path (architecture/platform-golden-path) receive a catalogue entry and a CODEOWNERS file from the template, so ownership exists from the first commit.

10. Exceptions

1. The repository maintainer requests an exception with the rule ID, scope, reason, compensating control and end date.
2. The policy owner approves; AppSec is consulted for OWN-POL-005, OWN-POL-006 and OWN-POL-007.
3. Exceptions are reviewed at expiry and in the annual policy review.

11. Compliance measurement

Example: In Q3, 39 of 41 repositories had a valid file (95.1%). The comparison job found 4 of 120 components with a mismatch, so catalogue agreement was 116 / 120 = 96.7%, below target; all four were caused by the payments split and fixed by the transfer in 8.4. Review attainment for the web team was 412 of 480 reviews (85.8%); the team added a second rota slot for its overlap with the Asia-Pacific region.

Report monthly to engineering leads and quarterly in Delivery Performance Report (dev/delivery-performance-report). Report by team, never by person.

12. Review cycle and related documents

Review this policy at least annually, after every reorganisation that changes team boundaries, after a security incident in which ownership was unclear, and when the source platform changes its code owner features.

Related documents:

• Branching Strategy (dev/branching-strategy) for protection rules that enforce code owner review.
• CI/CD Pipeline Design (dev/ci-cd-pipeline-design) for pipeline file ownership and promotion approvals.
• Dependency Management Policy (dev/dependency-management-policy) and Vulnerability Management Policy (security/vulnerability-management-policy) for owner maintenance duties.
• Secure Coding Standard (security/secure-coding-standard) for what specialist owners check on sensitive paths.
• Contributing guide (dev/contributing), Governance (dev/governance) and Pull Request template (dev/pull-request) for contributors.
• Team API (architecture/team-api) and Platform Golden Path (architecture/platform-golden-path) for team interfaces and new service scaffolding.
• Software Supply Chain Security Assessment (security/supply-chain-security) for source review evidence in the SLSA assessment.

13. Glossary and references

13.1 Glossary

13.2 References

Standard and licence note

Based on the code owner features described in GitHub Docs (About code owners; GitHub documentation is published under CC BY 4.0) and GitLab Docs (Code Owners; GitLab documentation is published under CC BY-SA 4.0; facts are paraphrased, no text adapted), and on the SLSA specification v1.2 Source track, used with attribution to the SLSA project (slsa.dev) under the Community Specification License 1.0. Platform behaviour is paraphrased and may change; check the current platform documentation before relying on it. GitHub and GitLab are trademarks of their owners; this template is not affiliated with or endorsed by them. Corvid Commerce is fictional. This template is original text written for this collection. Template licence: MIT.