# Protect a branch

Add a rule that constrains what may land on matching branches and how.

A rule matches a branch pattern such as `main` or `release/*`. The examples use the repository id
`5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60`.

## Rule fields

| Field                    | Effect                                                                                    | Default  |
| ------------------------ | ----------------------------------------------------------------------------------------- | -------- |
| `branchPattern`          | which branches the rule covers, e.g. `main`, `release/*`                                  | required |
| `requirePullRequest`     | direct pushes are refused; changes land through a merged pull request                     | `true`   |
| `requiredApprovals`      | 0–10 approving reviews before a merge is allowed; above 0, a pull request is required too | `0`      |
| `dismissStaleApprovals`  | approvals given on an earlier tip of the source branch do not count                       | `false`  |
| `requireCodeOwnerReview` | every changed file with owners needs an approval from one of them                         | `false`  |
| `requireStatusChecks`    | the required checks on the pull request must pass before a merge                          | `false`  |
| `requiredChecks`         | the check names that must pass (up to 50); derived from the target's workflows when empty | none     |
| `blockForcePush`         | force pushes to the branch are refused                                                    | `true`   |
| `blockDeletion`          | the branch cannot be deleted                                                              | `true`   |
| `requireMergeQueue`      | changes land only through the merge queue; see [Use a merge queue](use-a-merge-queue.md)  | `false`  |

The defaults are the API's. The Deutsche Cloud Console's form for a new rule starts with one required
approval. With zero required approvals and a required pull request, its own author can merge it.
A rule is checked on every push and on every ref the Deutsche Cloud Console writes, not only at merge time.

## Prerequisites

- Permission for `git:ManageBranchProtection` on the repository. Without it the Deutsche Cloud Console shows
  the rules but refuses **Add rule** and **Edit**, and the API answers 403.
- In the Deutsche Cloud Console, also `git:GetRepository` to open the repository's settings (without it the
  page is not found).

## Add a rule

**Console**
1. In the repository, choose **Settings**, then **Branch protection**.
2. Choose **Add rule**.
3. For **Branch pattern**, enter main.
4. Leave **Require pull request before merging** selected, and for **Required approvals**, enter
   2.
5. (Optional) Select **Dismiss stale approvals when new commits are pushed** or **Require review
   from code owners**.
6. (Optional) Select **Require status checks to pass before merging**, and for **Required
   checks**, enter workflow names separated by commas. Left empty, every workflow the branch runs
   for a pull request is required.
7. Leave **Block force pushes** and **Block deleting the branch** selected.
8. Choose **Create rule**. The rule is listed in the table with its pattern.

**CLI**
```sh
dcloud git branch-protection create 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 \
  --branch-pattern main --require-pull-request --required-approvals 2 \
  --require-status-checks --required-checks CI
```

**API**
```http
POST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/branch-protection
{ "branchPattern": "main", "requirePullRequest": true, "requiredApprovals": 2, "requireStatusChecks": true, "requiredChecks": ["CI"] }
```

**Terraform**
```hcl
resource "dcloud_git_branch_protection" "main" {
  repository_id         = dcloud_git_repository.this.id
  branch_pattern        = "main"
  require_pull_request  = true
  required_approvals    = 2
  require_status_checks = true
  required_checks       = ["CI"]
  block_force_push      = true
  block_deletion        = true
}
```

## Result

A push the rule refuses says why:

```
branch "main" is protected — changes must go through a pull request with 2 approving reviews
```

The other refusals read `branch "main" is protected and does not allow non-fast-forward pushes`,
`branch "main" is protected and cannot be deleted`, and, with a merge queue,
`branch "main" requires a merge queue — add the pull request to the queue instead`. A merge
without enough approvals is refused with
`Branch "main" requires 2 approving reviews — this pull request has 1.`

## Change a rule

In the rule's actions menu, choose **Edit**, change the fields and choose **Save changes**. With
the API, send only the fields that change with
`PATCH /git/api/repositories/{repoId}/branch-protection/{ruleId}` (`dcloud git branch-protection update`);
the fields you leave out keep their values, and an empty body is refused with `Nothing to update`.
Editing in place matters: creating a replacement and deleting the old rule leaves the branch
unprotected in between.

## Delete a rule

In the rule's actions menu, choose **Edit**, then **Delete this rule**, and confirm with **Delete
rule**. With the API, send `DELETE /git/api/repositories/{repoId}/branch-protection/{ruleId}`
(`dcloud git branch-protection delete`). The branch is unprotected from then on; existing commits and
pull requests are not changed.

## Related

- [Require review from code owners](require-code-owner-review.md)
- [Merge a pull request](merge-a-pull-request.md)
- [Require checks before a merge](/docs/ci-cd-pipeline)
- `git.branch-protection.create` · `dcloud git branch-protection create` · `dcloud_git_branch_protection`
