Create CodeOwners doc

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/)

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)

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
+<path-pattern> <owner> [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