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 | 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:ManageBranchProtectionon 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:GetRepositoryto open the repository's settings (without it the page is not found).
Add a rule
- In the repository, choose Settings, then Branch protection.
- Choose Add rule.
- For Branch pattern, enter main.
- Leave Require pull request before merging selected, and for Required approvals, enter 2.
- (Optional) Select Dismiss stale approvals when new commits are pushed or Require review from code owners.
- (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.
- Leave Block force pushes and Block deleting the branch selected.
- Choose Create rule. The rule is listed in the table with its pattern.
dcloud git branch-protection create 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 \
--branch-pattern main --require-pull-request --required-approvals 2 \
--require-status-checks --required-checks CIPOST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/branch-protection
{ "branchPattern": "main", "requirePullRequest": true, "requiredApprovals": 2, "requireStatusChecks": true, "requiredChecks": ["CI"] }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 reviewsThe 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.