# Require review from code owners

Name the owners of paths in a CODEOWNERS file, ask them to review, and require their approval before a merge.

When a pull request opens, the owners of the files it changes (up to 25, never its author) are
asked to review it, whether or not the rule is on. With the rule turned on, every changed file
that has owners needs an approval from one of them before the pull request merges, through
**Merge pull request**, auto-merge or the merge queue. Only each reviewer's latest vote counts,
and the author's approval never does.

## Prerequisites

- Permission for `git:PushRepository` to commit the file, and `git:ManageBranchProtection` to
  change the rule.
- In the Deutsche Cloud Console, also `git:GetRepository` to open the repository's settings (without it the
  page is not found).

## Step 1: Write the CODEOWNERS file

Put a `CODEOWNERS` file in `.github/`, the root or `docs/`; the first that exists counts. The
format is GitHub's: a path pattern, then its owners. The last matching line wins, and a pattern
with no owners un-owns its files.

```
*            @platform
/web/        @web-team
*.md         docs-lead@example.com
/vendor/
```

An owner is `@<IAM username>`, `@<IAM group>` (`@acme/web-team` works too: the part after the slash
is the group) or the email of a member. The file is read from the target branch, so a pull request
cannot change who reviews it.

## Step 2: Turn on the rule

**Console**
1. In the repository, choose **Settings**, then **Branch protection**.
2. In the actions menu of the rule for main, choose **Edit**.
3. Select **Require review from code owners**.
4. Choose **Save changes**.

**CLI**
```sh
dcloud git branch-protection update 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 \
  8a1f3c2d-4b5e-4f60-9a7b-8c9d0e1f2a3b --require-code-owner-review
```

**API**
```http
PATCH /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/branch-protection/8a1f3c2d-4b5e-4f60-9a7b-8c9d0e1f2a3b
{ "requireCodeOwnerReview": true }
```

**Terraform**
```hcl
resource "dcloud_git_branch_protection" "main" {
  repository_id             = dcloud_git_repository.this.id
  branch_pattern            = "main"
  require_code_owner_review = true
}
```

`5d6c2a1e-…` is the repository id and `8a1f3c2d-…` the rule's id
(`dcloud git branch-protection list`).

## Result

A pull request that changes owned files shows the owners as requested reviewers, and cannot merge
until one owner of each such file approves. The merge is refused with, for example:

```
Code owners must approve: 2 changed files (e.g. web/app.ts) need an approval from @web-team.
```

When the author is the only owner of the files still waiting, the message says so instead
(`Only the author owns web/app.ts in CODEOWNERS, and authors cannot approve their own pull request. …`):
add another owner for those files, or change the rule. Without a CODEOWNERS file on the target
branch, the rule requires nothing.

## Related

- [Protect a branch](protect-a-branch.md)
- [Review a pull request](review-a-pull-request.md)
