diff --git a/docs/how-to/README.md b/docs/how-to/README.md index 380937b3..b63c0f73 100644 --- a/docs/how-to/README.md +++ b/docs/how-to/README.md @@ -8,7 +8,11 @@ 1. [Submit Pull Request (PR)](submit-pull-request) 1. [Review Pull Request (PR)](review-pull-request) -## [Account Provisioning](account-provisioning/) +## Git + +1. [Git Procedures](git/README.md) + +## [Account Provisioning](account-provisioning/README.md) 1. [Create New AWS Accounts](/cloud-information/aws/documentation/account-setup/) 1. [Ansible setup for Baseline of Account](account-provisioning-ansible/) diff --git a/docs/how-to/git/README.md b/docs/how-to/git/README.md index 28d58a5a..2fdf445f 100644 --- a/docs/how-to/git/README.md +++ b/docs/how-to/git/README.md @@ -1,5 +1,6 @@ # Git Information, Details and Procedures * [Git Workflow](workflow.md) +* [CODEOWNERS](codeowners.md) * [Add a user to git-secret](add-user-to-git-secret.md) * [Github to Gitlab Migration](github-to-gitlab.md) diff --git a/docs/how-to/git/codeowners.md b/docs/how-to/git/codeowners.md new file mode 100644 index 00000000..208c00be --- /dev/null +++ b/docs/how-to/git/codeowners.md @@ -0,0 +1,119 @@ +# CODEOWNERS: Ownership and Review Routing + +This document explains how CODEOWNERS works and how we implement it in Terraform repositories. + +## What CODEOWNERS does + +`CODEOWNERS` is a path-to-reviewer mapping file. When a pull request changes files that match a rule, +the listed owners are automatically requested for review. + +In practice, this gives us: + +* consistent routing of reviews to the correct subject-matter teams +* reduced manual reviewer selection +* a repeatable control for sensitive paths (SSO, SCPs, account baseline, etc.) + +## Where we keep it + +We keep matching files in both locations: + +* `.github/CODEOWNERS` +* `.gitlab/CODEOWNERS` + +Both should contain the same rules unless a platform-specific exception is intentional and documented. + +## Rule format + +Each rule is one line: + +```text + [owner...] +``` + +Examples: + +```text +infrastructure/global/sso/ @terraform/reviewers-idc +infrastructure/global/sso/users_groups.yml @terraform/reviewers-idc-admin +``` + +Notes: + +* comments start with `#` +* owners can be teams and/or individual users +* use repository-relative paths +* more specific rules should come after broader rules + +## Matching and precedence + +CODEOWNERS matching is path-based with wildcard support. + +Precedence rule: + +* if multiple rules match a file, the **last matching rule** wins + +Because of this, we list broad rules first and then narrow exceptions later. + +## Implementation pattern we use + +Below is the current style used for global infrastructure ownership: + +```text +infrastructure/global/* @terraform/reviewers-accounts +infrastructure/global/organization/ @terraform/reviewers-accounts +infrastructure/global/sso/ @terraform/reviewers-idc +infrastructure/global/sso/users_groups.yml @terraform/reviewers-idc-admin +infrastructure/global/sso/permissionsets/ALL/* @terraform/reviewers-idc-admin +infrastructure/global/sso/permissionsets/inf* @terraform/reviewers-idc-admin +infrastructure/global/sso/permissionsets/csvd-servicecatalog-admin/ @terraform/reviewers-idc-admin +infrastructure/global/sso/permissionsets/sc-*/sc-* @terraform/reviewers-idc-admin +infrastructure/global/sso/permissionsets/sc-servicecatalog-t3/* @terraform/reviewers-idc-admin @brow0041 @andra315 +infrastructure/global/service-control-policies/ @terraform/reviewers-scp +infrastructure/global/tag-policies/ @terraform/reviewers-tag-policy +``` + +Why this order works: + +* `infrastructure/global/*` sets a default owner for global infrastructure +* `sso/` overrides that default for identity-related paths +* specific files/directories under `sso/permissionsets/` override `sso/` +* the final `sc-servicecatalog-t3/*` line adds individual reviewers for that specific area + +## How to add or change a rule + +1. Pick the narrowest path that represents the ownership boundary. +1. Choose the team alias first (individuals only when needed). +1. Place general rules above specific exceptions. +1. Update both `.github/CODEOWNERS` and `.gitlab/CODEOWNERS`. +1. Open a PR that touches representative files and verify reviewer auto-assignment. + +## Review enforcement + +For CODEOWNERS to be mandatory, branch protection must require code owner review. + +Typical setup: + +* require pull request review before merge +* require review from code owners +* keep required status checks enabled + +If branch protection is not configured, CODEOWNERS may still request reviewers but will not block merges. + +## Common pitfalls + +* placing specific rules above broad rules (causes unexpected owner selection) +* updating only one platform file (`.github` or `.gitlab`) and creating drift +* using overly broad patterns that route too many PRs to one team +* adding only individuals and not team aliases, which creates maintenance overhead + +## Quick validation checklist + +* Rules are ordered broad to specific. +* Team aliases are correct and active. +* `.github/CODEOWNERS` and `.gitlab/CODEOWNERS` are in sync. +* Test PR confirms expected reviewer requests. + +# CHANGELOG + +* 1.0.0 -- 2026-04-22 + - initial \ No newline at end of file