diff --git a/.gitlab/CODEOWNERS b/.gitlab/CODEOWNERS
index 72056df92e159b1dd4c7b6447fa244ef30ea6e6f..8cf292fbf2bd5e9356a6669488454f62fff16421 100644
--- a/.gitlab/CODEOWNERS
+++ b/.gitlab/CODEOWNERS
@@ -1068,7 +1068,7 @@ lib/gitlab/checks/**
/doc/user/project/organize_work_with_projects.md @lciutacu
/doc/user/project/pages/ @msedlakjakubowski
/doc/user/project/project_topics.md @lciutacu
-/doc/user/project/protected_branches.md @brendan777
+/doc/user/project/repository/branches/protected.md @brendan777
/doc/user/project/protected_tags.md @brendan777
/doc/user/project/quick_actions.md @msedlakjakubowski
/doc/user/project/releases/ @phillipwells
diff --git a/app/assets/javascripts/projects/settings/branch_rules/components/edit/branch_dropdown.vue b/app/assets/javascripts/projects/settings/branch_rules/components/edit/branch_dropdown.vue
index 6494456d56000e772f43ffd508b39f691c95532a..49ac035246485b1a89c082bbd075dcc2484856fa 100644
--- a/app/assets/javascripts/projects/settings/branch_rules/components/edit/branch_dropdown.vue
+++ b/app/assets/javascripts/projects/settings/branch_rules/components/edit/branch_dropdown.vue
@@ -54,7 +54,7 @@ export default {
},
},
searchInputDelay: 250,
- wildcardsHelpPath: helpPagePath('user/project/protected_branches', {
+ wildcardsHelpPath: helpPagePath('user/project/repository/branches/protected', {
anchor: 'protect-multiple-branches-with-wildcard-rules',
}),
props: {
diff --git a/app/assets/javascripts/projects/settings/branch_rules/components/edit/protections/index.vue b/app/assets/javascripts/projects/settings/branch_rules/components/edit/protections/index.vue
index bcc0f64d667364738dffe0fd9d3f65d28aa03734..95a6aac9cc8671de26eb52db16b7706d0fbd464a 100644
--- a/app/assets/javascripts/projects/settings/branch_rules/components/edit/protections/index.vue
+++ b/app/assets/javascripts/projects/settings/branch_rules/components/edit/protections/index.vue
@@ -21,7 +21,7 @@ export default {
PushProtections,
MergeProtections,
},
- protectedBranchesHelpPath: helpPagePath('user/project/protected_branches'),
+ protectedBranchesHelpPath: helpPagePath('user/project/repository/branches/protected'),
props: {
protections: {
type: Object,
diff --git a/app/assets/javascripts/projects/settings/branch_rules/components/view/index.vue b/app/assets/javascripts/projects/settings/branch_rules/components/view/index.vue
index 3c3c8b4477b9e434eec057f5eb7fc38908cc2f23..323fe24866b54df22604dcebc251c29fd58aaaea 100644
--- a/app/assets/javascripts/projects/settings/branch_rules/components/view/index.vue
+++ b/app/assets/javascripts/projects/settings/branch_rules/components/view/index.vue
@@ -42,7 +42,7 @@ import {
EDIT_RULE_MODAL_ID,
} from './constants';
-const protectedBranchesHelpDocLink = helpPagePath('user/project/protected_branches');
+const protectedBranchesHelpDocLink = helpPagePath('user/project/repository/branches/protected');
const codeOwnersHelpDocLink = helpPagePath('user/project/codeowners/index');
const pushRulesHelpDocLink = helpPagePath('user/project/repository/push_rules');
diff --git a/app/assets/javascripts/projects/settings/components/branch_rule_modal.vue b/app/assets/javascripts/projects/settings/components/branch_rule_modal.vue
index dfadc4efbdadc23aa8ea7ba3120108965e5907c7..9a983575de0195cf6abc897f56f4ae5d00d67c25 100644
--- a/app/assets/javascripts/projects/settings/components/branch_rule_modal.vue
+++ b/app/assets/javascripts/projects/settings/components/branch_rule_modal.vue
@@ -4,7 +4,7 @@ import { helpPagePath } from '~/helpers/help_page_helper';
import { s__ } from '~/locale';
import getProtectableBranches from '../graphql/queries/protectable_branches.query.graphql';
-const wildcardsHelpDocLink = helpPagePath('user/project/protected_branches', {
+const wildcardsHelpDocLink = helpPagePath('user/project/repository/branches/protected', {
anchor: 'protect-multiple-branches-with-wildcard-rules',
});
export default {
diff --git a/app/views/protected_branches/shared/_create_protected_branch.html.haml b/app/views/protected_branches/shared/_create_protected_branch.html.haml
index 4efb4196375e7930854b6189edbb250ce473f8e1..4998259df98fe27078c0e55292ae4031324acb12 100644
--- a/app/views/protected_branches/shared/_create_protected_branch.html.haml
+++ b/app/views/protected_branches/shared/_create_protected_branch.html.haml
@@ -13,10 +13,10 @@
- else
= render partial: "protected_branches/shared/dropdown", locals: { f: f, toggle_classes: '!gl-w-full gl-form-input-lg' }
.form-text.text-muted
- - wildcards_url = help_page_url('user/project/protected_branches', anchor: 'protect-multiple-branches-with-wildcard-rules')
+ - wildcards_url = help_page_url('user/project/repository/branches/protected', anchor: 'protect-multiple-branches-with-wildcard-rules')
- wildcards_link_tag_pair = tag_pair(link_to('', wildcards_url, target: '_blank', rel: 'noopener noreferrer'), :wildcards_link_start, :wildcards_link_end)
- - case_sensitive_url = help_page_url('user/project/protected_branches', anchor: 'branch-names-are-case-sensitive')
+ - case_sensitive_url = help_page_url('user/project/repository/branches/protected', anchor: 'branch-names-are-case-sensitive')
- case_sensitive_link_tag_pair = tag_pair(link_to('', case_sensitive_url, target: '_blank', rel: 'noopener noreferrer'), :case_sensitive_link_start, :case_sensitive_link_end)
- code_tag_pair = tag_pair(tag.code, :code_tag_start, :code_tag_end)
diff --git a/app/views/protected_branches/shared/_index.html.haml b/app/views/protected_branches/shared/_index.html.haml
index 6ff5e30eefd82113be18076e7b8498a6311b106c..ad62bc2977c762be3cb9d9072dcbd209192d77e1 100644
--- a/app/views/protected_branches/shared/_index.html.haml
+++ b/app/views/protected_branches/shared/_index.html.haml
@@ -7,7 +7,7 @@
expanded: expanded) do |c|
- c.with_description do
= s_("ProtectedBranch|Keep stable branches secure and force developers to use merge requests.")
- = link_to s_("ProtectedBranch|What are protected branches?"), help_page_path("user/project/protected_branches")
+ = link_to s_("ProtectedBranch|What are protected branches?"), help_page_path("user/project/repository/branches/protected")
- c.with_body do
.js-alert-protected-branch-created-container.gl-mt-5
@@ -25,7 +25,7 @@
toggle_options: { data: { testid: 'add-protected-branch-button' } }) do |c|
- c.with_description do
= s_("ProtectedBranch|By default, protected branches restrict who can modify the branch.")
- = link_to s_("ProtectedBranch|Learn more."), help_page_path("user/project/protected_branches", anchor: "who-can-modify-a-protected-branch")
+ = link_to s_("ProtectedBranch|Learn more."), help_page_path("user/project/repository/branches/protected", anchor: "who-can-modify-a-protected-branch")
- c.with_body do
= content_for :branches_list
diff --git a/data/deprecations/16-0-source-code-branch-push.yml b/data/deprecations/16-0-source-code-branch-push.yml
index ee32a486db1ad6b5103c730664d319b87f94a85a..424753823ec84974d601d95babec480ee42b6252 100644
--- a/data/deprecations/16-0-source-code-branch-push.yml
+++ b/data/deprecations/16-0-source-code-branch-push.yml
@@ -6,11 +6,11 @@
stage: Create
issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/12776
body: | # (required) Do not modify this line, instead modify the lines below.
- GitLab administrators can no longer perform actions on protected branches or tags unless they have been explicitly granted that permission. These actions include pushing and merging into a [protected branch](https://docs.gitlab.com/ee/user/project/protected_branches.html), unprotecting a branch, and creating [protected tags](https://docs.gitlab.com/ee/user/project/protected_tags.html).
+ GitLab administrators can no longer perform actions on protected branches or tags unless they have been explicitly granted that permission. These actions include pushing and merging into a [protected branch](https://docs.gitlab.com/ee/user/project/repository/branches/protected.html), unprotecting a branch, and creating [protected tags](https://docs.gitlab.com/ee/user/project/protected_tags.html).
#
# OPTIONAL FIELDS
#
tiers: # (optional - may be required in the future) An array of tiers that the feature is available in currently. e.g., [Free, Silver, Gold, Core, Premium, Ultimate]
- documentation_url: https://docs.gitlab.com/ee/user/project/protected_branches.html
+ documentation_url: https://docs.gitlab.com/ee/user/project/repository/branches/protected.html
image_url: # (optional) This is a link to a thumbnail image depicting the feature
video_url: # (optional) Use the youtube thumbnail URL with the structure of https://img.youtube.com/vi/UNIQUEID/hqdefault.jpg
diff --git a/data/whats_new/202102180001_13_09.yml b/data/whats_new/202102180001_13_09.yml
index d6b4011f08963da74cc45f12712e816c5672fef8..b46a79ee1f2a02091c6f99c82db7d8f3582d476a 100644
--- a/data/whats_new/202102180001_13_09.yml
+++ b/data/whats_new/202102180001_13_09.yml
@@ -116,7 +116,7 @@
self-managed: true
gitlab-com: true
available_in: [Free, Premium, Ultimate]
- documentation_link: https://docs.gitlab.com/ee/user/project/protected_branches.html#allow-deploy-keys-to-push-to-a-protected-branch
+ documentation_link: https://docs.gitlab.com/ee/user/project/repository/branches/protected.html#allow-deploy-keys-to-push-to-a-protected-branch
image_url: https://about.gitlab.com/images/13_9/deploy_keys.png
published_at: 2021-02-22
release: 13.9
diff --git a/doc/administration/compliance.md b/doc/administration/compliance.md
index 5802eb6293399c8efb2d3ac89ee569be4738c1dc..8030a70ea31dcbf405262e54c3ce1737899e4e2a 100644
--- a/doc/administration/compliance.md
+++ b/doc/administration/compliance.md
@@ -28,7 +28,7 @@ and secure supply chain best practices:
| [Granular user roles<br/>and flexible permissions](../user/permissions.md) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Manage access and permissions with five different user roles and settings for external users. Set permissions according to people's role, rather than either read or write access to a repository. Don't share the source code with people that only need access to the issue tracker. |
| [Merge request approvals](../user/project/merge_requests/approvals/index.md) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Configure approvals required for merge requests. |
| [Push rules](../user/project/repository/push_rules.md) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Control pushes to your repositories. |
-| Separation of duties using<br/>[protected branches](../user/project/protected_branches.md#require-code-owner-approval-on-a-protected-branch) and<br/>[custom CI/CD configuration paths](../ci/pipelines/settings.md#specify-a-custom-cicd-configuration-file) | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Leverage the GitLab cross-project YAML configurations to define deployers of code and developers of code. See how to use this setup to define these roles in the [Separation of Duties deploy project](https://gitlab.com/guided-explorations/separation-of-duties-deploy/blob/master/README.md) and the [Separation of Duties project](https://gitlab.com/guided-explorations/separation-of-duties/blob/master/README.md). |
+| Separation of duties using<br/>[protected branches](../user/project/repository/branches/protected.md#require-code-owner-approval-on-a-protected-branch) and<br/>[custom CI/CD configuration paths](../ci/pipelines/settings.md#specify-a-custom-cicd-configuration-file) | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Leverage the GitLab cross-project YAML configurations to define deployers of code and developers of code. See how to use this setup to define these roles in the [Separation of Duties deploy project](https://gitlab.com/guided-explorations/separation-of-duties-deploy/blob/master/README.md) and the [Separation of Duties project](https://gitlab.com/guided-explorations/separation-of-duties/blob/master/README.md). |
| [Security policies](../user/application_security/policies/index.md) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Configure customizable policies that require merge request approval based on policy rules, or enforce security scanners to execute in project pipelines for compliance requirements. Policies can be enforced granularly against specific projects, or all projects in a group or subgroup. |
## Compliant workflow automation
diff --git a/doc/api/branches.md b/doc/api/branches.md
index 49367c0b2f2e17a8cac775dc1b5297981aef9975..39e5229a5ff1dfd6004c24f7ea23c8599c4ff158 100644
--- a/doc/api/branches.md
+++ b/doc/api/branches.md
@@ -231,7 +231,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
Deletes all branches that are merged into the project's default branch.
NOTE:
-[Protected branches](../user/project/protected_branches.md) are not deleted as part of this operation.
+[Protected branches](../user/project/repository/branches/protected.md) are not deleted as part of this operation.
```plaintext
DELETE /projects/:id/repository/merged_branches
@@ -253,5 +253,5 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
## Related topics
- [Branches](../user/project/repository/branches/index.md)
-- [Protected branches](../user/project/protected_branches.md)
+- [Protected branches](../user/project/repository/branches/protected.md)
- [Protected branches API](protected_branches.md)
diff --git a/doc/api/group_protected_branches.md b/doc/api/group_protected_branches.md
index 99d411546356cfa301fc1decf989e2204626303e..a389b292234b595fa21242cca1e0af10f28a9a0a 100644
--- a/doc/api/group_protected_branches.md
+++ b/doc/api/group_protected_branches.md
@@ -227,7 +227,7 @@ Elements in the `allowed_to_push` / `allowed_to_merge` / `allowed_to_unprotect`
form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}`. Each user must have
access to the project and each group must
[have this project shared](../user/project/members/sharing_projects_groups.md). These access levels
-allow [more granular control over protected branch access](../user/project/protected_branches.md).
+allow [more granular control over protected branch access](../user/project/repository/branches/protected.md).
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md
index 5a5f0cd9a619e3d9c1130a462fb274805066a6b2..e12550d638838e0d6a4af8386f6110482408f6af 100644
--- a/doc/api/protected_branches.md
+++ b/doc/api/protected_branches.md
@@ -25,7 +25,7 @@ The access levels are defined in the `ProtectedRefAccess.allowed_access_levels`
> - Deploy key information [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116846) in GitLab 16.0.
-Gets a list of [protected branches](../user/project/protected_branches.md) from a project
+Gets a list of [protected branches](../user/project/repository/branches/protected.md) from a project
as they are defined in the UI. If a wildcard is set, it is returned instead of the exact name
of the branches that match that wildcard.
@@ -321,7 +321,7 @@ DETAILS:
**Offering:** GitLab.com, Self-managed, GitLab Dedicated
Elements in the `allowed_to_push` / `allowed_to_merge` / `allowed_to_unprotect` array should take the
-form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}`. Each user must have access to the project and each group must [have this project shared](../user/project/members/sharing_projects_groups.md). These access levels allow [more granular control over protected branch access](../user/project/protected_branches.md).
+form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}`. Each user must have access to the project and each group must [have this project shared](../user/project/members/sharing_projects_groups.md). These access levels allow [more granular control over protected branch access](../user/project/repository/branches/protected.md).
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&allowed_to_push%5B%5D%5Buser_id%5D=1"
@@ -562,6 +562,6 @@ Example response:
## Related topics
-- [Protected branches](../user/project/protected_branches.md)
+- [Protected branches](../user/project/repository/branches/protected.md)
- [Branches](../user/project/repository/branches/index.md)
- [Branches API](branches.md)
diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md
index e42cabbc51529a85949a399a5ce8bac77f9edf8c..7cdeceb526a9b5ab926b0d82d5e0015b376a2ef7 100644
--- a/doc/ci/environments/deployment_safety.md
+++ b/doc/ci/environments/deployment_safety.md
@@ -140,7 +140,7 @@ page.
Production secrets are needed to deploy successfully. For example, when deploying to the cloud,
cloud providers require these secrets to connect to their services. In the project settings, you can
define and protect CI/CD variables for these secrets. [Protected variables](../variables/index.md#protect-a-cicd-variable)
-are only passed to pipelines running on [protected branches](../../user/project/protected_branches.md)
+are only passed to pipelines running on [protected branches](../../user/project/repository/branches/protected.md)
or [protected tags](../../user/project/protected_tags.md).
The other pipelines don't get the protected variable. You can also
[scope variables to specific environments](../variables/where_variables_can_be_used.md#variables-with-an-environment-scope).
diff --git a/doc/ci/jobs/job_control.md b/doc/ci/jobs/job_control.md
index d25c525c4dd35186507f48b3b1db33315d96c97b..83fd45daea998ba480a84f07ef77b5ba1f397cff 100644
--- a/doc/ci/jobs/job_control.md
+++ b/doc/ci/jobs/job_control.md
@@ -24,7 +24,7 @@ in the `.gitlab-ci.yml` file.
By default, manual jobs display as skipped when the pipeline starts.
-You can use [protected branches](../../user/project/protected_branches.md) to more strictly
+You can use [protected branches](../../user/project/repository/branches/protected.md) to more strictly
[protect manual deployments](#protect-manual-jobs) from being run by unauthorized users.
### Types of manual jobs
diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md
index 1a3c0e79ec30a3a270ff1d8cd35885b276e28b03..d68a0804f70d220d2caab4050ff091fd6694401d 100644
--- a/doc/ci/pipelines/index.md
+++ b/doc/ci/pipelines/index.md
@@ -243,10 +243,10 @@ related objects, such as jobs, logs, artifacts, and triggers.
### Pipeline security on protected branches
A strict security model is enforced when pipelines are executed on
-[protected branches](../../user/project/protected_branches.md).
+[protected branches](../../user/project/repository/branches/protected.md).
The following actions are allowed on protected branches if the user is
-[allowed to merge or push](../../user/project/protected_branches.md)
+[allowed to merge or push](../../user/project/repository/branches/protected.md)
to that specific branch:
- Run manual pipelines (using the [Web UI](#run-a-pipeline-manually) or [pipelines API](#pipelines-api)).
diff --git a/doc/ci/pipelines/schedules.md b/doc/ci/pipelines/schedules.md
index 25ddb52ec4ad12eeb3e87333e350d398253db34c..e8119a5ff6fbbf21a8494a6a5c19cc2868dc758a 100644
--- a/doc/ci/pipelines/schedules.md
+++ b/doc/ci/pipelines/schedules.md
@@ -17,7 +17,7 @@ Use scheduled pipelines to run GitLab CI/CD [pipelines](index.md) at regular int
For a scheduled pipeline to run:
- The schedule owner must have the Developer role. For pipelines on protected branches,
- the schedule owner must be [allowed to merge](../../user/project/protected_branches.md#add-protection-to-existing-branches)
+ the schedule owner must be [allowed to merge](../../user/project/repository/branches/protected.md#add-protection-to-existing-branches)
to the branch.
- The `.gitlab-ci.yml` file must have valid syntax.
diff --git a/doc/ci/runners/configure_runners.md b/doc/ci/runners/configure_runners.md
index 891d9315b2a0c36e00b9d4963d3b837c40399654..e4efc307ef200062061e8f45ec0bffe0db5864fa 100644
--- a/doc/ci/runners/configure_runners.md
+++ b/doc/ci/runners/configure_runners.md
@@ -247,7 +247,7 @@ For more information about token rotation, see
## Prevent runners from revealing sensitive information
To ensure runners don't reveal sensitive information, you can configure them to only run jobs
-on [protected branches](../../user/project/protected_branches.md), or jobs that have [protected tags](../../user/project/protected_tags.md).
+on [protected branches](../../user/project/repository/branches/protected.md), or jobs that have [protected tags](../../user/project/protected_tags.md).
Runners configured to run jobs on protected branches cannot run jobs in [merge request pipelines](../pipelines/merge_request_pipelines.md).
@@ -957,7 +957,7 @@ defined in the `.gitlab-ci.yml` file. If the name is not defined, the default fi
The provenance metadata is generated in the [in-toto attestation format](https://github.com/in-toto/attestation) for spec version [1.0](https://github.com/in-toto/attestation/tree/v1.0/spec).
-To use an SLSA v1.0 statement, set the `SLSA_PROVENANCE_SCHEMA_VERSION=v1` variable in the `.gitlab-ci.yml` file.
+To use an SLSA v1.0 statement, set the `SLSA_PROVENANCE_SCHEMA_VERSION=v1` variable in the `.gitlab-ci.yml` file.
The following fields are populated by default:
diff --git a/doc/ci/secrets/hashicorp_vault.md b/doc/ci/secrets/hashicorp_vault.md
index 7b99d1c865e042f73fc13260426a4fae761abe77..695021cdd868feba598683c211216c24852a1829 100644
--- a/doc/ci/secrets/hashicorp_vault.md
+++ b/doc/ci/secrets/hashicorp_vault.md
@@ -211,7 +211,7 @@ EOF
This example uses [bound claims](https://developer.hashicorp.com/vault/api-docs/auth/jwt#bound_claims)
to specify that only a JWT with matching values for the specified claims is allowed to authenticate.
-Combined with [protected branches](../../user/project/protected_branches.md),
+Combined with [protected branches](../../user/project/repository/branches/protected.md),
you can restrict who is able to authenticate and read the secrets.
Any of the claims [included in the JWT](#how-it-works) can be matched against a list of values
@@ -349,7 +349,7 @@ and GitLab features. For example, restrict the token by:
of specific users.
- Setting Vault time limits for TTL of the token as specified in [`token_explicit_max_ttl`](https://developer.hashicorp.com/vault/api-docs/auth/jwt#token_explicit_max_ttl),
where the token expires after authentication.
-- Scoping the JWT to [GitLab protected branches](../../user/project/protected_branches.md)
+- Scoping the JWT to [GitLab protected branches](../../user/project/repository/branches/protected.md)
that are restricted to a subset of project users.
- Scoping the JWT to [GitLab protected tags](../../user/project/protected_tags.md),
that are restricted to a subset of project users.
diff --git a/doc/ci/secrets/index.md b/doc/ci/secrets/index.md
index 564d49611cd8904e0733fd80b20d6afa2d19a334..e699c696706bdfb639450e178fc9aff19760885d 100644
--- a/doc/ci/secrets/index.md
+++ b/doc/ci/secrets/index.md
@@ -206,7 +206,7 @@ references. You can have as many bounded claims you need, but they must *all* ma
for authentication to be successful.
Combining bounded claims with GitLab features like [user roles](../../user/permissions.md)
-and [protected branches](../../user/project/protected_branches.md), you can tailor
+and [protected branches](../../user/project/repository/branches/protected.md), you can tailor
these rules to fit your specific use case. In this example, authentication is allowed
only for jobs running for protected tags with names matching the pattern used for
production releases:
diff --git a/doc/ci/variables/index.md b/doc/ci/variables/index.md
index ee596f01da1b573a320669d0f7f03244797b3d15..4fe5815a3f4b992eff3998edc763065bf88e1d9f 100644
--- a/doc/ci/variables/index.md
+++ b/doc/ci/variables/index.md
@@ -149,7 +149,7 @@ To add or update variables in the project settings:
- **Environment scope**: Optional. **All (default)** (`*`), a specific [environment](../environments/index.md#types-of-environments),
or a wildcard [environment scope](../environments/index.md#limit-the-environment-scope-of-a-cicd-variable).
- **Protect variable** Optional. If selected, the variable is only available
- in pipelines that run on [protected branches](../../user/project/protected_branches.md) or [protected tags](../../user/project/protected_tags.md).
+ in pipelines that run on [protected branches](../../user/project/repository/branches/protected.md) or [protected tags](../../user/project/protected_tags.md).
- **Visibility**:
- **Visible**: The variable's **Value** is visible in job logs and shown in variables settings.
- **Masked**: The variable's **Value** is masked in job logs, but it is still shown in variables settings.
@@ -335,7 +335,7 @@ Different versions of [GitLab Runner](../runners/index.md) have different maskin
### Protect a CI/CD variable
You can configure a project, group, or instance CI/CD variable to be available
-only to pipelines that run on [protected branches](../../user/project/protected_branches.md)
+only to pipelines that run on [protected branches](../../user/project/repository/branches/protected.md)
or [protected tags](../../user/project/protected_tags.md).
[Merged results pipelines](../pipelines/merged_results_pipelines.md) and [merge request pipelines](../pipelines/merge_request_pipelines.md) do not have access to these variables.
diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md
index e0fa03bdf0b36b8d29dd206df11342102a66338a..f3a8e0f43435bb28330d85a1297a21a98d40f298 100644
--- a/doc/ci/variables/predefined_variables.md
+++ b/doc/ci/variables/predefined_variables.md
@@ -189,14 +189,14 @@ and the merge request must be open.
| `CI_MERGE_REQUEST_PROJECT_URL` | The URL of the project of the merge request. For example, `http://192.168.10.15:3000/namespace/awesome-project`. |
| `CI_MERGE_REQUEST_REF_PATH` | The ref path of the merge request. For example, `refs/merge-requests/1/head`. |
| `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME` | The source branch name of the merge request. |
-| `CI_MERGE_REQUEST_SOURCE_BRANCH_PROTECTED` | `true` when the source branch of the merge request is [protected](../../user/project/protected_branches.md). Introduced in GitLab 16.4. |
+| `CI_MERGE_REQUEST_SOURCE_BRANCH_PROTECTED` | `true` when the source branch of the merge request is [protected](../../user/project/repository/branches/protected.md). Introduced in GitLab 16.4. |
| `CI_MERGE_REQUEST_SOURCE_BRANCH_SHA` | The HEAD SHA of the source branch of the merge request. The variable is empty in merge request pipelines. The SHA is present only in [merged results pipelines](../pipelines/merged_results_pipelines.md). |
| `CI_MERGE_REQUEST_SOURCE_PROJECT_ID` | The ID of the source project of the merge request. |
| `CI_MERGE_REQUEST_SOURCE_PROJECT_PATH` | The path of the source project of the merge request. |
| `CI_MERGE_REQUEST_SOURCE_PROJECT_URL` | The URL of the source project of the merge request. |
| `CI_MERGE_REQUEST_SQUASH_ON_MERGE` | `true` when the [squash on merge](../../user/project/merge_requests/squash_and_merge.md) option is set. Introduced in GitLab 16.4. |
| `CI_MERGE_REQUEST_TARGET_BRANCH_NAME` | The target branch name of the merge request. |
-| `CI_MERGE_REQUEST_TARGET_BRANCH_PROTECTED` | `true` when the target branch of the merge request is [protected](../../user/project/protected_branches.md). Introduced in GitLab 15.2. |
+| `CI_MERGE_REQUEST_TARGET_BRANCH_PROTECTED` | `true` when the target branch of the merge request is [protected](../../user/project/repository/branches/protected.md). Introduced in GitLab 15.2. |
| `CI_MERGE_REQUEST_TARGET_BRANCH_SHA` | The HEAD SHA of the target branch of the merge request. The variable is empty in merge request pipelines. The SHA is present only in [merged results pipelines](../pipelines/merged_results_pipelines.md). |
| `CI_MERGE_REQUEST_TITLE` | The title of the merge request. |
diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md
index ab0a84169cf2f30900a73590ee78734f9fefbc85..2b17430e86bf68acdab79c4604cdcbfa5d4be45a 100644
--- a/doc/ci/yaml/index.md
+++ b/doc/ci/yaml/index.md
@@ -314,7 +314,7 @@ include:
- Using a specific SHA hash, which should be the most stable option. Use the
full 40-character SHA hash to ensure the desired commit is referenced, because
using a short SHA hash for the `ref` might be ambiguous.
- - Applying both [protected branch](../../user/project/protected_branches.md) and [protected tag](../../user/project/protected_tags.md#prevent-tag-creation-with-the-same-name-as-branches) rules to
+ - Applying both [protected branch](../../user/project/repository/branches/protected.md) and [protected tag](../../user/project/protected_tags.md#prevent-tag-creation-with-the-same-name-as-branches) rules to
the `ref` in the other project. Protected tags and branches are more likely to pass through change management before changing.
#### `include:remote`
@@ -345,7 +345,7 @@ include:
- Be careful when including another project's CI/CD configuration file. No pipelines or notifications trigger
when the other project's files change. From a security perspective, this is similar to
pulling a third-party dependency. If you link to another GitLab project you own, consider the use of both
- [protected branches](../../user/project/protected_branches.md) and [protected tags](../../user/project/protected_tags.md#prevent-tag-creation-with-the-same-name-as-branches)
+ [protected branches](../../user/project/repository/branches/protected.md) and [protected tags](../../user/project/protected_tags.md#prevent-tag-creation-with-the-same-name-as-branches)
to enforce change management rules.
#### `include:template`
@@ -1653,7 +1653,7 @@ cache between jobs. You can only use paths that are in the local working copy.
Caches are:
- Shared between pipelines and jobs.
-- By default, not shared between [protected](../../user/project/protected_branches.md) and unprotected branches.
+- By default, not shared between [protected](../../user/project/repository/branches/protected.md) and unprotected branches.
- Restored before [artifacts](#artifacts).
- Limited to a maximum of four [different caches](../caching/index.md#use-multiple-caches).
@@ -1889,7 +1889,7 @@ rspec:
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362114) in GitLab 15.8.
-Use `cache:unprotect` to set a cache to be shared between [protected](../../user/project/protected_branches.md)
+Use `cache:unprotect` to set a cache to be shared between [protected](../../user/project/repository/branches/protected.md)
and unprotected branches.
WARNING:
diff --git a/doc/ci/yaml/workflow.md b/doc/ci/yaml/workflow.md
index de5ad11d627c8493c984597f5888b4721d3b738c..a783336c68986245b9b3fbf670dc4656570ca575 100644
--- a/doc/ci/yaml/workflow.md
+++ b/doc/ci/yaml/workflow.md
@@ -134,7 +134,7 @@ workflow:
- if: $CI_COMMIT_REF_PROTECTED == "true"
```
-This example assumes that your long-lived branches are [protected](../../user/project/protected_branches.md).
+This example assumes that your long-lived branches are [protected](../../user/project/repository/branches/protected.md).
### Skip pipelines for draft merge requests
diff --git a/doc/security/hardening_cicd_recommendations.md b/doc/security/hardening_cicd_recommendations.md
index 72f3bc8e7b8d70c94e2e642af86033fee4b74f15..81260d2b6f8fa275681361d5d93235f02e09caf7 100644
--- a/doc/security/hardening_cicd_recommendations.md
+++ b/doc/security/hardening_cicd_recommendations.md
@@ -44,7 +44,7 @@ of the users of a project. They are a core component of CD/CD.
By default, only the default branch gets a protected pipeline. An owner of a project
can ensure that other branches are protected by
-[configuring a protected branch](../user/project/protected_branches.md).
+[configuring a protected branch](../user/project/repository/branches/protected.md).
This allows for more restricted security on pipelines. For more information, see
[pipeline security on a protected branch](../ci/pipelines/index.md#pipeline-security-on-protected-branches).
diff --git a/doc/security/hardening_nist_800_53.md b/doc/security/hardening_nist_800_53.md
index 7b1e1f8dee6500bbf28d2d1b5163dbf9ba35a37f..31e222a988948573a447d9e9713ce8e771ef6014 100644
--- a/doc/security/hardening_nist_800_53.md
+++ b/doc/security/hardening_nist_800_53.md
@@ -420,7 +420,7 @@ consider where that pipeline will run. Connecting to external services
may violate an established authorization boundary where federal data is
permitted to be stored and processed. GitLab provides runner container
images configured to run on FIPS-enabled systems. GitLab provides
-hardening guidance for pipelines, including how to [configure protected branches](../user/project/protected_branches.md)
+hardening guidance for pipelines, including how to [configure protected branches](../user/project/repository/branches/protected.md)
and [implement pipeline security](../ci/pipelines/index.md#pipeline-security-on-protected-branches).
Additionally, customers may want to consider assigning [required checks](../user/project/merge_requests/status_checks.md)
before merging code to ensure that all checks have passed prior to
diff --git a/doc/security/information_exclusivity.md b/doc/security/information_exclusivity.md
index 8d0840a36f40bf40ca9ddafa28a8c3fef72f9a20..d150305476dbec5fea50f16bb94cd0c519d7c01b 100644
--- a/doc/security/information_exclusivity.md
+++ b/doc/security/information_exclusivity.md
@@ -28,7 +28,7 @@ You can take steps to prevent unintentional sharing and information
destruction. This limitation is the reason why only certain people are allowed
to [add users to a project](../user/project/members/index.md)
and why only a GitLab administrator can
-[force push a protected branch](../user/project/protected_branches.md).
+[force push a protected branch](../user/project/repository/branches/protected.md).
<!-- ## Troubleshooting
diff --git a/doc/subscriptions/bronze_starter.md b/doc/subscriptions/bronze_starter.md
index 824e7a2aa069fca8e7cb2bb8db1c2500b8ba7e16..a48f5b9ee9d8746b34b9eb4c8f53b9a9e989943f 100644
--- a/doc/subscriptions/bronze_starter.md
+++ b/doc/subscriptions/bronze_starter.md
@@ -70,7 +70,7 @@ the tiers are no longer mentioned in GitLab documentation:
- [Required Approvals](../user/project/merge_requests/approvals/index.md#required-approvals)
- [Code Owners as eligible approvers](../user/project/merge_requests/approvals/rules.md#code-owners-as-eligible-approvers)
- [Approval rules](../user/project/merge_requests/approvals/rules.md) features
- - [Restricting push and merge access to certain users](../user/project/protected_branches.md)
+ - [Restricting push and merge access to certain users](../user/project/repository/branches/protected.md)
- Metrics and analytics:
- [Contribution Analytics](../user/group/contribution_analytics/index.md)
- [Merge Request Analytics](../user/analytics/merge_request_analytics.md)
diff --git a/doc/topics/git/git_rebase.md b/doc/topics/git/git_rebase.md
index 52a993e83eca1af86d4e4db8b1529defc94e9b55..e5d5677f053bc6931e10934f86a66452cd839d6d 100644
--- a/doc/topics/git/git_rebase.md
+++ b/doc/topics/git/git_rebase.md
@@ -225,11 +225,11 @@ these more destructive changes from happening accidentally.
Force pushing is not recommended on shared branches, because you risk destroying
others' changes.
-If the branch you want to force push is [protected](../../user/project/protected_branches.md),
+If the branch you want to force push is [protected](../../user/project/repository/branches/protected.md),
you can't force push to it unless you either:
- Unprotect it.
-- [Allow force pushes](../../user/project/protected_branches.md#allow-force-push-on-a-protected-branch)
+- [Allow force pushes](../../user/project/repository/branches/protected.md#allow-force-push-on-a-protected-branch)
to it.
Then you can force push and protect it again.
diff --git a/doc/tutorials/scan_result_policy/index.md b/doc/tutorials/scan_result_policy/index.md
index ba91e64f6938d4d4b23abc8e285925499637c00b..ee7cae4c82c178a56a4421ecbfd22f83cfdfc72e 100644
--- a/doc/tutorials/scan_result_policy/index.md
+++ b/doc/tutorials/scan_result_policy/index.md
@@ -34,7 +34,7 @@ The namespace used for this tutorial must:
- **Project name**: `sast-scan-result-policy`.
- Select the **Enable Static Application Security Testing (SAST)** checkbox.
1. Select **Create project**.
-1. Go to the newly created project and create [protected branches](../../user/project/protected_branches.md).
+1. Go to the newly created project and create [protected branches](../../user/project/repository/branches/protected.md).
## Add a merge request approval policy
diff --git a/doc/update/deprecations.md b/doc/update/deprecations.md
index 7e99b5914a75b549b2e6b59c64e33c467c7e1ad7..b835e368d41cbd214dbe876a0c771f9c8d266289 100644
--- a/doc/update/deprecations.md
+++ b/doc/update/deprecations.md
@@ -3721,7 +3721,7 @@ GitLab 16.0.
</div>
-GitLab administrators can no longer perform actions on protected branches or tags unless they have been explicitly granted that permission. These actions include pushing and merging into a [protected branch](https://docs.gitlab.com/ee/user/project/protected_branches.html), unprotecting a branch, and creating [protected tags](https://docs.gitlab.com/ee/user/project/protected_tags.html).
+GitLab administrators can no longer perform actions on protected branches or tags unless they have been explicitly granted that permission. These actions include pushing and merging into a [protected branch](https://docs.gitlab.com/ee/user/project/repository/branches/protected.html), unprotecting a branch, and creating [protected tags](https://docs.gitlab.com/ee/user/project/protected_tags.html).
</div>
diff --git a/doc/user/application_security/policies/merge_request_approval_policies.md b/doc/user/application_security/policies/merge_request_approval_policies.md
index 890da31496624f58cfb673fed6a302bc1c83a4fd..f5f44dea6e85b4b01537a5e5592b736d050a58c0 100644
--- a/doc/user/application_security/policies/merge_request_approval_policies.md
+++ b/doc/user/application_security/policies/merge_request_approval_policies.md
@@ -34,7 +34,7 @@ The following video gives you an overview of GitLab merge request approval polic
## Restrictions
-- You can enforce merge request approval policies only on [protected](../../project/protected_branches.md)
+- You can enforce merge request approval policies only on [protected](../../project/repository/branches/protected.md)
target branches.
- You can assign a maximum of five rules to each policy.
- You can assign a maximum of five merge request approval policies to each security policy project.
diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md
index 4d31986fdb8cb353127ec2b95c37908ba015fd4b..28b52f04ca28d31e53f531d6c5e78c771f86f558 100644
--- a/doc/user/clusters/agent/ci_cd_workflow.md
+++ b/doc/user/clusters/agent/ci_cd_workflow.md
@@ -345,7 +345,7 @@ The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
-To restrict access to the agent to only jobs run on [protected branches](../../project/protected_branches.md):
+To restrict access to the agent to only jobs run on [protected branches](../../project/repository/branches/protected.md):
- Add `protected_branches_only: true` to `ci_access.projects` or `ci_access.groups`.
For example:
diff --git a/doc/user/clusters/agent/gitops/example_repository_structure.md b/doc/user/clusters/agent/gitops/example_repository_structure.md
index a181cfa28ee45a66110fdd73c07ef79b51ec44fa..8088ac8e9142e0437422889176f0ca49d2a929f2 100644
--- a/doc/user/clusters/agent/gitops/example_repository_structure.md
+++ b/doc/user/clusters/agent/gitops/example_repository_structure.md
@@ -83,7 +83,7 @@ To create a deployment branch:
1. Create a [CI/CD variable](../../../../ci/variables/index.md) with a token value named `DEPLOYMENT_TOKEN`.
Remember to [mask](../../../../ci/variables/index.md#mask-a-cicd-variable) the value so that it won't show in
job logs.
-1. Add a rule to [protect](../../../../user/project/protected_branches.md)
+1. Add a rule to [protect](../../../../user/project/repository/branches/protected.md)
your deployment branch with the following values:
- Allowed to merge: No one.
diff --git a/doc/user/compliance/license_approval_policies.md b/doc/user/compliance/license_approval_policies.md
index 21d4e33ecb2c52c6f27e5d02cc4c244da45a556b..3986a3a9b0e3f62fd5fcd90dfbffc01e4818f471 100644
--- a/doc/user/compliance/license_approval_policies.md
+++ b/doc/user/compliance/license_approval_policies.md
@@ -16,7 +16,7 @@ DETAILS:
Use license approval policies to specify criteria that determines when approval is required before a merge request can be merged.
NOTE:
-License approval policies are applicable to [protected](../project/protected_branches.md) target branches only.
+License approval policies are applicable to [protected](../project/repository/branches/protected.md) target branches only.
The following video provides an overview of these policies.
diff --git a/doc/user/group/import/migrated_items.md b/doc/user/group/import/migrated_items.md
index 2a35602342da10e53a8bdefee96f65987921c5d1..f5237bc2b1a2119476c177a0093baf26b168fc18 100644
--- a/doc/user/group/import/migrated_items.md
+++ b/doc/user/group/import/migrated_items.md
@@ -139,7 +139,7 @@ Project items that are migrated to the destination GitLab instance include:
**Footnotes:**
-1. Imported branches respect the [default branch protection settings](../../project/protected_branches.md)
+1. Imported branches respect the [default branch protection settings](../../project/repository/branches/protected.md)
of the destination group, which could cause an unprotected branch to be imported as protected.
1. See [User contributions and membership mapping](direct_transfer_migrations.md#user-contributions-and-membership-mapping).
diff --git a/doc/user/permissions.md b/doc/user/permissions.md
index 4a2cdb1ba6d08903b580415c384f1e7555010f3b..82f9d6fe61eaa29e4c0b55837f514d5147e293e3 100644
--- a/doc/user/permissions.md
+++ b/doc/user/permissions.md
@@ -310,19 +310,19 @@ Project permissions for [repository](project/repository/index.md) features inclu
| View project code | ✓ | ✓ | ✓ | ✓ | ✓ | On self-managed GitLab instances, users with the Guest role are able to perform this action only on public and internal projects (not on private projects). [External users](../administration/external_users.md) must be given explicit access (at least the **Reporter** role) even if the project is internal. Users with the Guest role on GitLab.com are only able to perform this action on public projects because internal visibility is not available. In GitLab 15.9 and later, users with the Guest role and an Ultimate license can view private repository content if an administrator (on self-managed or GitLab Dedicated) or group owner (on GitLab.com) gives those users permission. The administrator or group owner can create a [custom role](custom_roles.md) through the API or UI and assign that role to the users. |
| Pull project code | ✓ | ✓ | ✓ | ✓ | ✓ | On self-managed GitLab instances, users with the Guest role are able to perform this action only on public and internal projects (not on private projects). [External users](../administration/external_users.md) must be given explicit access (at least the **Reporter** role) even if the project is internal. Users with the Guest role on GitLab.com are only able to perform this action on public projects because internal visibility is not available. |
| View a commit status | | ✓ | ✓ | ✓ | ✓ | |
-| Create or update commit status | | | ✓ | ✓ | ✓ | If the [branch is protected](project/protected_branches.md), this depends on the access given to Developers and Maintainers. |
+| Create or update commit status | | | ✓ | ✓ | ✓ | If the [branch is protected](project/repository/branches/protected.md), this depends on the access given to Developers and Maintainers. |
| Create and delete [Git tags](project/repository/tags/index.md) | | | ✓ | ✓ | ✓ | |
| Create new [branches](project/repository/branches/index.md) | | | ✓ | ✓ | ✓ | |
| Force push to non-protected branches | | | ✓ | ✓ | ✓ | |
| Push to non-protected branches | | | ✓ | ✓ | ✓ | |
| Delete non-protected branches | | | ✓ | ✓ | ✓ | |
-| Manage [protected branches](project/protected_branches.md) | | | | ✓ | ✓ | |
+| Manage [protected branches](project/repository/branches/protected.md) | | | | ✓ | ✓ | |
| Delete protected branches | | | | ✓ | ✓ | |
| Manage [protected tags](project/protected_tags.md) | | | | ✓ | ✓ | |
| Manage [push rules](project/repository/push_rules.md) | | | | ✓ | ✓ | |
-| Push to protected branches | | | | ✓ | ✓ | If the [branch is protected](project/protected_branches.md), this depends on the access given to Developers and Maintainers. |
+| Push to protected branches | | | | ✓ | ✓ | If the [branch is protected](project/repository/branches/protected.md), this depends on the access given to Developers and Maintainers. |
| Remove fork relationship | | | | | ✓ | |
-| Force push to protected branches | | | | | | Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [protected branches](project/protected_branches.md#allow-force-push-on-a-protected-branch). |
+| Force push to protected branches | | | | | | Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [protected branches](project/repository/branches/protected.md#allow-force-push-on-a-protected-branch). |
Project permissions for [merge requests](project/merge_requests/index.md):
@@ -572,7 +572,7 @@ To work around the issue, give these users the Guest role or higher to any proje
- [Custom roles](custom_roles.md)
- [The GitLab principles behind permissions](https://handbook.gitlab.com/handbook/product/gitlab-the-product/#permissions-in-gitlab)
- [Members](project/members/index.md)
-- Customize permissions on [protected branches](project/protected_branches.md)
+- Customize permissions on [protected branches](project/repository/branches/protected.md)
- [LDAP user permissions](group/access_and_permissions.md#manage-group-memberships-via-ldap)
- [Value stream analytics permissions](group/value_stream_analytics/index.md#access-permissions-for-value-stream-analytics)
- [Project aliases](../user/project/working_with_projects.md#project-aliases)
diff --git a/doc/user/project/codeowners/index.md b/doc/user/project/codeowners/index.md
index d1d0da52c86edf3cecc90e1d8cf0b7388a67d94f..a95b431e85597f588fd2c97f0e8b83452bff5c49 100644
--- a/doc/user/project/codeowners/index.md
+++ b/doc/user/project/codeowners/index.md
@@ -67,7 +67,7 @@ Prerequisites:
1. Define some rules in the file following the [Code Owners syntax reference](reference.md).
Some suggestions:
- Configure [All eligible approvers](../merge_requests/approvals/rules.md#code-owners-as-eligible-approvers) approval rule.
- - [Require Code Owner approval](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) on a protected branch.
+ - [Require Code Owner approval](../repository/branches/protected.md#require-code-owner-approval-on-a-protected-branch) on a protected branch.
1. Commit your changes, and push them up to GitLab.
### `CODEOWNERS` file
diff --git a/doc/user/project/codeowners/troubleshooting.md b/doc/user/project/codeowners/troubleshooting.md
index cc7a9870853ff93d250e6abd922bef38918a5ea2..c4f82730396fe8e4a903e04174b82647797d2b27 100644
--- a/doc/user/project/codeowners/troubleshooting.md
+++ b/doc/user/project/codeowners/troubleshooting.md
@@ -22,7 +22,7 @@ A Code Owner approval rule is optional if any of these conditions are true:
- The user or group is not a member of the project.
Code Owners [cannot inherit members from parent groups](https://gitlab.com/gitlab-org/gitlab/-/issues/288851/).
-- [Code Owner approval on a protected branch](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) has not been set up.
+- [Code Owner approval on a protected branch](../repository/branches/protected.md#require-code-owner-approval-on-a-protected-branch) has not been set up.
- The section is [marked as optional](index.md#make-a-code-owners-section-optional).
- No eligible code owners are available to approve the merge request due to conflicts
with other [merge request approval settings](../merge_requests/approvals/settings.md).
diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md
index 6a901fa6fdb69fd175f02998ef0ae727d4f5fe64..f3f0aafc404066e0a7ea4d13a166c87b94191902 100644
--- a/doc/user/project/deploy_keys/index.md
+++ b/doc/user/project/deploy_keys/index.md
@@ -46,7 +46,7 @@ permissions only applies for the current project.
GitLab authorizes the creator of the deploy key if the Git-command triggers additional processes. For example:
-- When a deploy key is used to push a commit to a [protected branch](../protected_branches.md),
+- When a deploy key is used to push a commit to a [protected branch](../repository/branches/protected.md),
the _creator_ of the deploy key must have access to the branch.
- When a deploy key is used to push a commit that triggers a CI/CD pipeline, the _creator_ of the
deploy key must have access to the CI/CD resources, including protected environments and secret
@@ -188,13 +188,13 @@ What happens to the deploy key when it is disabled depends on the following:
### Deploy key cannot push to a protected branch
There are a few scenarios where a deploy key fails to push to a
-[protected branch](../protected_branches.md).
+[protected branch](../repository/branches/protected.md).
- The owner associated to a deploy key does not have [membership](../members/index.md) to the project of the protected branch.
- The owner associated to a deploy key has [project membership permissions](../../../user/permissions.md#project-members-permissions) lower than required to **View project code**.
- The deploy key does not have [read-write permissions for the project](#edit-project-access-permissions-of-a-deploy-key).
- The deploy key has been [revoked](#revoke-project-access-of-a-deploy-key).
-- **No one** is selected in [the **Allowed to push and merge** section](../protected_branches.md#add-protection-to-existing-branches) of the protected branch.
+- **No one** is selected in [the **Allowed to push and merge** section](../repository/branches/protected.md#add-protection-to-existing-branches) of the protected branch.
All deploy keys are associated to an account. Since the permissions for an account can change, this might lead to scenarios where a deploy key that was working is suddenly unable to push to a protected branch.
diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md
index b24e72c4e982f40fd1c17a9c071cde9806ce1830..4d1ef81c5242a0fa0d4c0dba15220660852e5a35 100644
--- a/doc/user/project/import/github.md
+++ b/doc/user/project/import/github.md
@@ -368,11 +368,11 @@ When they are imported, supported GitHub branch protection rules are mapped to e
| GitHub rule | GitLab rule | Introduced in |
|:----------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------|
| **Require conversation resolution before merging** for the project's default branch | **All threads must be resolved** [project setting](../merge_requests/index.md#prevent-merge-unless-all-threads-are-resolved) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/371110) |
-| **Require a pull request before merging** | **No one** option in the **Allowed to push and merge** list of [branch protection settings](../protected_branches.md#add-protection-to-existing-branches) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370951) |
+| **Require a pull request before merging** | **No one** option in the **Allowed to push and merge** list of [branch protection settings](../repository/branches/protected.md#add-protection-to-existing-branches) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370951) |
| **Require signed commits** for the project's default branch | **Reject unsigned commits** GitLab [push rule](../repository/push_rules.md#prevent-unintended-consequences) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370949) |
-| **Allow force pushes - Everyone** | **Allowed to force push** [branch protection setting](../protected_branches.md#allow-force-push-on-a-protected-branch) | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/370943) |
-| **Require a pull request before merging - Require review from Code Owners** | **Require approval from code owners** [branch protection setting](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/376683) |
-| **Require a pull request before merging - Allow specified actors to bypass required pull requests** | List of users in the **Allowed to push and merge** list of [branch protection settings](../protected_branches.md#add-protection-to-existing-branches). Without a **Premium** subscription, the list of users that are allowed to push and merge is limited to roles. | [GitLab 15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/384939) |
+| **Allow force pushes - Everyone** | **Allowed to force push** [branch protection setting](../repository/branches/protected.md#allow-force-push-on-a-protected-branch) | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/370943) |
+| **Require a pull request before merging - Require review from Code Owners** | **Require approval from code owners** [branch protection setting](../repository/branches/protected.md#require-code-owner-approval-on-a-protected-branch) | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/376683) |
+| **Require a pull request before merging - Allow specified actors to bypass required pull requests** | List of users in the **Allowed to push and merge** list of [branch protection settings](../repository/branches/protected.md#add-protection-to-existing-branches). Without a **Premium** subscription, the list of users that are allowed to push and merge is limited to roles. | [GitLab 15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/384939) |
Mapping GitHub rule **Require status checks to pass before merging** to
[external status checks](../merge_requests/status_checks.md) was considered in issue
diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md
index 3fae41c9ff15a03c59b70b945eb7739a997883c7..4990b0e58fa1923eee99085f9f48a62586fca60a 100644
--- a/doc/user/project/merge_requests/approvals/rules.md
+++ b/doc/user/project/merge_requests/approvals/rules.md
@@ -187,7 +187,7 @@ become eligible approvers in the project. To enable this merge request approval
1. In the **Approvals required** column, enter the number of approvals required.
You can also
-[require code owner approval](../../protected_branches.md#require-code-owner-approval-on-a-protected-branch)
+[require code owner approval](../../repository/branches/protected.md#require-code-owner-approval-on-a-protected-branch)
for protected branches.
## Enable approval permissions for users with the Reporter role
@@ -204,7 +204,7 @@ Prerequisites:
To enable approval permissions for these users without granting them push access:
-1. [Create a protected branch](../../protected_branches.md)
+1. [Create a protected branch](../../repository/branches/protected.md)
1. [Create a new group](../../../group/index.md#create-a-group).
1. [Add the user to the group](../../../group/index.md#add-users-to-a-group),
and select the Reporter role for the user.
@@ -279,7 +279,7 @@ approval rule for certain branches:
- To apply the rule to all protected branches, select **All protected branches**.
- To apply the rule to a specific branch, select it from the list.
1. To enable this configuration, follow
- [Require Code Owner approval on a protected branch](../../protected_branches.md#require-code-owner-approval-on-a-protected-branch).
+ [Require Code Owner approval on a protected branch](../../repository/branches/protected.md#require-code-owner-approval-on-a-protected-branch).
## Security Approvals
diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md
index e0acc194ec6fbae44b63e9287861c71dc0797f59..616f277fa1dda93524a6cc94357121684130dd6f 100644
--- a/doc/user/project/merge_requests/authorization_for_merge_requests.md
+++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md
@@ -13,7 +13,7 @@ DETAILS:
There are two main ways to have a merge request flow with GitLab:
-1. Working with [protected branches](../protected_branches.md) in a single repository.
+1. Working with [protected branches](../repository/branches/protected.md) in a single repository.
1. Working with forks of an authoritative project.
## Protected branch flow
@@ -48,7 +48,7 @@ To set up a protected branch flow:
explicitly has the option to push or force push, consider making those branches protected:
- [Manage and Protect Branches](../repository/branches/index.md#manage-and-protect-branches)
- - [Protected Branches](../protected_branches.md)
+ - [Protected Branches](../repository/branches/protected.md)
1. Each change to the code comes through as a commit.
You can specify the format and security measures such as requiring SSH key signing for changes
diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md
index 3c0388ebd74d6c39c5669445001b1dea3aee4d54..72154f3d89c5702320814fbd1e51d36fdf0550a1 100644
--- a/doc/user/project/merge_requests/status_checks.md
+++ b/doc/user/project/merge_requests/status_checks.md
@@ -132,7 +132,7 @@ you can use this field to set this limit.
-The branches list is populated from the projects [protected branches](../protected_branches.md).
+The branches list is populated from the projects [protected branches](../repository/branches/protected.md).
You can scroll through the list of branches or use the search box
when there are a lot of branches and the branch you are looking
diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md
index 23ce29f18f772ad2e2f78079a9ba9b999295099f..28eb87452fa0a757d5dd6550b7d68bd69de8eda0 100644
--- a/doc/user/project/protected_branches.md
+++ b/doc/user/project/protected_branches.md
@@ -1,425 +1,11 @@
---
-stage: Create
-group: Source Code
-info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
-description: "Protected branches in GitLab restrict who can push to, merge, or modify a Git branch."
+redirect_to: 'repository/branches/protected.md'
+remove_date: '2024-12-12'
---
-# Protected branches
+This document was moved to [another location](repository/branches/protected.md).
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, Self-managed, GitLab Dedicated
-
-In GitLab, [permissions](../permissions.md) are fundamentally defined around the
-idea of having read or write permission to the repository and branches. To impose
-further restrictions on certain branches, they can be protected.
-
-A protected branch controls:
-
-- Which users can merge into the branch.
-- Which users can push to the branch.
-- If users can force push to the branch.
-- If changes to files listed in the CODEOWNERS file can be pushed directly to the branch.
-- Which users, groups, or access levels can unprotect the branch using the
- [Protected branches API](../../api/protected_branches.md#update-a-protected-branch).
-- Which users can modify the branch with the [Commits API](../../api/commits.md).
-
-The [default branch](repository/branches/default.md) for your repository is protected by default.
-
-## Who can modify a protected branch
-
-> - Branch push permission [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118532) to require GitLab administrators to also have the **allowed** permission in GitLab 16.0.
-
-When a branch is protected, the default behavior enforces these restrictions on the branch.
-
-| Action | Who can do it |
-|:-------------------------|:----------------------------------------|
-| Protect a branch | At least the Maintainer role. |
-| Push to the branch | Anyone with **Allowed** permission. (1) |
-| Force push to the branch | No one. (3) |
-| Delete the branch | No one. (2) |
-
-1. Users with the Developer role can create a project in a group, but might not be allowed to
- initially push to the [default branch](repository/branches/default.md).
-1. No one can delete a protected branch using Git commands, however, users with at least Maintainer
- role can [delete a protected branch from the UI or API](#delete-a-protected-branch).
-1. If the `group_protected_branches` feature flag is enabled _and_ the same branch is
- protected at both the group and project levels, force push settings configured
- for that branch at the project level are ignored. All other protections continue
- to use project level settings.
-
-You can implement a [merge request approval policy](../application_security/policies/merge_request_approval_policies.md#approval_settings)
-to prevent protected branches being unprotected or deleted.
-
-### When a branch matches multiple rules
-
-When a branch matches multiple rules, the **most permissive rule** determines the
-level of protection for the branch. For example, consider these rules, which include
-[wildcards](#protect-multiple-branches-with-wildcard-rules):
-
-| Branch name pattern | Allowed to merge | Allowed to push and merge |
-|---------------------|------------------------|---------------------------|
-| `v1.x` | Maintainer | Maintainer |
-| `v1.*` | Maintainer + Developer | Maintainer |
-| `v*` | No one | No one |
-
-A branch named `v1.x` is a case-sensitive match for all three branch name patterns: `v1.x`, `v1.*`, and `v*`.
-As the most permissive option determines the behavior, the resulting permissions for branch `v1.x` are:
-
-- **Allowed to merge:** Of the three settings, `Maintainer + Developer` is most permissive,
- and controls branch behavior as a result. Even though the branch also matched `v1.x` and `v*`
- (which each have stricter permissions), users with the Developer role can merge into the branch.
-- **Allowed to push and merge:** Of the three settings, `Maintainer` is the most permissive, and controls
- branch behavior as a result. Even though branches matching `v*` are set to `No one`, branches
- that _also_ match `v1.x` or `v1.*` receive the more permissive `Maintainer` permission.
-
-To be certain that a rule controls the behavior of a branch,
-_all_ other patterns that match must apply less or equally permissive rules.
-
-If you want to ensure that `No one` is allowed to push to branch `v1.x`, every pattern
-that matches `v1.x` must set `Allowed to push and merge` to `No one`, like this:
-
-| Branch name pattern | Allowed to merge | Allowed to push and merge |
-|---------------------|------------------------|---------------------------|
-| `v1.x` | Maintainer | No one |
-| `v1.*` | Maintainer + Developer | No one |
-| `v*` | No one | No one |
-
-### Set the default branch protection level
-
-Administrators can set a default branch protection level in the
-[**Admin** area](../project/repository/branches/default.md#instance-level-default-branch-protection).
-
-## Add protection to existing branches
-
-Configure protected branches for all projects in a group, or just for a project.
-
-### For one project
-
-Prerequisites:
-
-- You must have at least the Maintainer role.
-- When granting a group **Allowed to merge** or **Allowed to push and merge** permissions
- on a protected branch, the group must be added to the project.
-
-To protect a branch:
-
-1. On the left sidebar, select **Search or go to** and find your project.
-1. Select **Settings > Repository**.
-1. Expand **Protected branches**.
-1. Select **Add protected branch**.
-1. From the **Branch** dropdown list, select the branch you want to protect.
-1. From the **Allowed to merge** list, select a role that can merge into this branch.
-1. From the **Allowed to push and merge** list, select a role that can push to this branch.
-
- NOTE:
- In GitLab Premium and Ultimate, you can also add groups or individual users
- to **Allowed to merge** and **Allowed to push and merge**.
-
-1. Select **Protect**.
-
-The protected branch displays in the list of protected branches.
-
-### For all projects in a group
-
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** Self-managed
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106532) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `group_protected_branches`. Disabled by default.
-
-FLAG:
-On self-managed GitLab, by default this feature is not available.
-To make it available, an administrator can
-[enable the feature flag](../../administration/feature_flags.md)
-named `group_protected_branches`. On GitLab.com and GitLab Dedicated, this feature is not available.
-
-Group owners can create protected branches for a group. These settings are inherited
-by all projects in the group and can't be overridden by project settings. If a
-specific branch is configured with **Allowed to force push** settings at both the
-group and project levels, the **Allowed to force push** setting at the _project_ level
-is ignored in favor of the group level setting.
-
-Prerequisites:
-
-- You must have the Owner role for the group.
-
-To protect a branch for all the projects in a group:
-
-1. On the left sidebar, select **Search or go to** and find your group.
-1. Select **Settings > Repository**.
-1. Expand **Protected branches**.
-1. Select **Add protected branch**.
-1. In the **Branch** text box, type the branch name or a wildcard.
- Branch names and wildcards [are case-sensitive](repository/branches/index.md#name-your-branch).
-1. From the **Allowed to merge** list, select a role that can merge into this branch.
-1. From the **Allowed to push and merge** list, select a role that can push to this branch.
-1. Select **Protect**.
-
-The protected branch is added to the list of protected branches.
-
-## Protect multiple branches with wildcard rules
-
-When using wildcards, multiple rules can apply to a single branch.
-If more than one rule applies to a branch, the _most permissive_ rule controls
-how the branch behaves. For merge controls to work properly, set
-**Allowed to push and merge** to a broader set of users than **Allowed to merge**.
-
-Prerequisites:
-
-- You must have at least the Maintainer role.
-
-To protect multiple branches at the same time:
-
-1. On the left sidebar, select **Search or go to** and find your project.
-1. Select **Settings > Repository**.
-1. Expand **Protected branches**.
-1. Select **Add protected branch**.
-1. From the **Branch** dropdown list, type the branch name and a wildcard.
- Branch names and wildcards [are case-sensitive](repository/branches/index.md#name-your-branch). For example:
-
- | Wildcard protected branch | Matching branches |
- |---------------------------|--------------------------------------------------------|
- | `*-stable` | `production-stable`, `staging-stable` |
- | `production/*` | `production/app-server`, `production/load-balancer` |
- | `*gitlab*` | `gitlab`, `gitlab/staging`, `master/gitlab/production` |
-
-1. From the **Allowed to merge** list, select a role that can merge into
- this branch.
-1. From the **Allowed to push and merge** list, select a role that can
- push to this branch. In GitLab Premium or Ultimate, you can also add groups or individual users.
-1. Select **Protect**.
-
-The protected branch displays in the list of protected branches.
-
-## Require everyone to submit merge requests for a protected branch
-
-You can force everyone to submit a merge request, rather than allowing them to
-check in directly to a protected branch:
-
-1. On the left sidebar, select **Search or go to** and find your project.
-1. Select **Settings > Repository**.
-1. Expand **Protected branches**.
-1. Select **Add protected branch**.
-1. From the **Branch** dropdown list, select the branch you want to protect.
-1. From the **Allowed to merge** list, select **Developers + Maintainers**.
-1. From the **Allowed to push and merge** list, select **No one**.
-1. Select **Protect**.
-
-Alternatively, you can [create](repository/branches/index.md#create-a-branch-rule) or [edit](repository/branches/index.md#edit-a-branch-rule) a branch rule. Then:
-
-1. Select **Edit** in the **Allowed to merge** section.
-1. Select **Developers and Maintainers**.
-1. Select **Save changes**.
-
-## Allow everyone to push directly to a protected branch
-
-You can allow everyone with write access to push to the protected branch.
-
-1. On the left sidebar, select **Search or go to** and find your project.
-1. Select **Settings > Repository**.
-1. Expand **Protected branches**.
-1. Select **Add protected branch**.
-1. From the **Branch** dropdown list, select the branch you want to protect.
-1. From the **Allowed to push and merge** list, select **Developers + Maintainers**.
-1. Select **Protect**.
-
-Alternatively, you can [create](repository/branches/index.md#create-a-branch-rule) or [edit](repository/branches/index.md#edit-a-branch-rule) a branch rule. Then:
-
-1. Select **Edit** in the **Allowed to push and merge** section.
-1. Select **Developers and Maintainers**.
-1. Select **Save changes**.
-
-## Allow deploy keys to push to a protected branch
-
-> - More restrictions on deploy keys [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/425926) in GitLab 16.5 [with a flag](../../administration/feature_flags.md) named `check_membership_in_protected_ref_access`. Disabled by default.
-
-You can push to a protected branch with a [deploy key](deploy_keys/index.md).
-
-Prerequisites:
-
-- The deploy key must be enabled for your project. A project deploy key is enabled by default when
- it is created. However, a public deploy key must be
- [granted](deploy_keys/index.md#grant-project-access-to-a-public-deploy-key) access to the
- project.
-- The deploy key must have [write access](deploy_keys/index.md#permissions) to your project
- repository.
-- The owner of the deploy key must have at least read access to the project.
-- If the `check_membership_in_protected_ref_access` feature flag is enabled, the owner of the
- deploy key must also be a member of the project.
-
-To allow a deploy key to push to a protected branch:
-
-1. On the left sidebar, select **Search or go to** and find your project.
-1. Select **Settings > Repository**.
-1. Expand **Protected branches**.
-1. Select **Add protected branch**.
-1. From the **Branch** dropdown list, select the branch you want to protect.
-1. From the **Allowed to push and merge** list, select the deploy key.
-1. Select **Protect**.
-
-Deploy keys are not available in the **Allowed to merge** dropdown list.
-
-## Allow force push on a protected branch
-
-You can allow [force pushes](../../topics/git/git_rebase.md#force-pushing) to
-protected branches.
-
-To protect a new branch and enable force push:
-
-1. On the left sidebar, select **Search or go to** and find your project.
-1. Select **Settings > Repository**.
-1. Expand **Protected branches**.
-1. Select **Add protected branch**.
-1. From the **Branch** dropdown list, select the branch you want to protect.
-1. From the **Allowed to push and merge** and **Allowed to merge** lists, select the settings you want.
-1. To allow all users with push access to force push, turn on the **Allowed to force push** toggle.
-1. Select **Protect**.
-
-To enable force pushes on branches that are already protected:
-
-1. On the left sidebar, select **Search or go to** and find your project.
-1. Select **Settings > Repository**.
-1. Expand **Protected branches**.
-1. Select **Add protected branch**.
-1. In the list of protected branches, next to the branch, turn on the **Allowed to force push** toggle.
-
-Alternatively, you can [create](repository/branches/index.md#create-a-branch-rule) or [edit](repository/branches/index.md#edit-a-branch-rule) a branch rule. Then:
-
-1. In the list of protected branches, next to the branch, turn on the **Allowed to force push** toggle.
-
-Members who can push to this branch can now also force push.
-
-### When a branch matches multiple rules
-
-When a branch matches multiple rules, the **most permissive rule** determines the
-level of protection for the branch. For example, consider these rules, which include
-[wildcards](#protect-multiple-branches-with-wildcard-rules):
-
-| Branch name pattern | Allow force push |
-|---------------------|------------------|
-| `v1.x` | Yes |
-| `v1.*` | No |
-| `v*` | No |
-
-A branch named `v1.x` matches all three branch name patterns: `v1.x`, `v1.*`, and `v*`.
-As the most permissive option determines the behavior, the resulting permissions for branch `v1.x` are:
-
-- **Allow force push:** Of the three settings, `Yes` is most permissive,
- and controls branch behavior as a result. Even though the branch also matched `v1.x` and `v*`
- (which each have stricter permissions), any user that can push to this branch can also force push.
-
-NOTE:
-Force push settings for a branch at the project level are overridden by group level settings
-if the `group_protected_branches` feature flag is enabled and a group owner has set
-[group level protection for the same branch](#for-all-projects-in-a-group).
-
-## Require Code Owner approval on a protected branch
-
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, Self-managed, GitLab Dedicated
-
-For a protected branch, you can require at least one approval by a [Code Owner](codeowners/index.md).
-If a branch is protected by multiple rules, code owner approval is required if _any_ of
-the applicable rules have **Required approval from code owners** enabled.
-
-To protect a new branch and enable Code Owner's approval:
-
-1. On the left sidebar, select **Search or go to** and find your project.
-1. Select **Settings > Repository**.
-1. Expand **Protected branches**.
-1. Select **Add protected branch**.
-1. From the **Branch** dropdown list, select the branch you want to protect.
-1. From the **Allowed to push and merge** and **Allowed to merge** lists, select the settings you want.
-1. Turn on the **Require approval from code owners** toggle.
-1. Select **Protect**.
-
-To enable Code Owner's approval on branches that are already protected:
-
-1. On the left sidebar, select **Search or go to** and find your project.
-1. Select **Settings > Repository**.
-1. Expand **Protected branches**.
-1. Select **Add protected branch**.
-1. In the list of protected branches, next to the branch, turn on the **Code owner approval** toggle.
-
-Alternatively, you can [create](repository/branches/index.md#create-a-branch-rule) or [edit](repository/branches/index.md#edit-a-branch-rule) a branch rule.
-Then, in the list of protected branches, next to the branch,
-turn on the **Code owner approval** toggle.
-
-When enabled, all merge requests for these branches require approval
-by a Code Owner per matched rule before they can be merged.
-Additionally, direct pushes to the protected branch are denied if a rule is matched.
-
-Any user who is not specified in the `CODEOWNERS` file cannot push
-changes for the specified files or paths, unless they are specifically allowed to.
-You don't have to restrict developers from pushing directly to the
-protected branch. Instead, you can restrict pushing to certain files where a review by
-Code Owners is required.
-
-In [GitLab Premium 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/35097), users and groups
-who are allowed to push to protected branches do not need a merge request to merge their feature branches.
-Thus, they can skip merge request approval rules, Code Owners included.
-
-## Run pipelines on protected branches
-
-The permission to merge or push to protected branches defines
-whether or not a user can run CI/CD pipelines and execute actions on jobs.
-
-Because [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md) run on the source
-branch, a pipeline isn't created if the user opening a merge request does not have permission to merge
-or push to the source branch.
-
-See [Security on protected branches](../../ci/pipelines/index.md#pipeline-security-on-protected-branches)
-for details about the pipelines security model.
-
-## Create a new branch with protections
-
-Prerequisites:
-
-- You must have at least the Developer role.
-- To create a protected branch, branch protection must be configured to
- [require everyone to submit merge requests for a protected branch](#require-everyone-to-submit-merge-requests-for-a-protected-branch).
-
-To create a new branch with protections:
-
-1. On the left sidebar, select **Search or go to** and find your project.
-1. Select **Code > Branches**.
-1. Select **New branch**.
-1. Fill in the branch name and select an existing branch, tag, or commit to
- base the new branch on. If you [require everyone to submit merge requests for a protected branch](#require-everyone-to-submit-merge-requests-for-a-protected-branch), only existing protected branches and commits
- that are already in protected branches are accepted.
-
-You can also use [the Branches API](../../api/branches.md) to create a branch with protections.
-
-If branch protection is configured to [allow everyone to push directly to a protected branch](#allow-everyone-to-push-directly-to-a-protected-branch), a branch with protections can also be created from the command line or a Git client application.
-
-## Delete a protected branch
-
-Users with at least the Maintainer role can manually delete protected
-branches by using the GitLab web interface:
-
-1. On the left sidebar, select **Search or go to** and find your project.
-1. Select **Code > Branches**.
-1. Next to the branch you want to delete, select **Delete** (**{remove}**).
-1. On the confirmation dialog, enter the branch name and select **Yes, delete protected branch**.
- Branch names [are case-sensitive](repository/branches/index.md#name-your-branch).
-
-Protected branches can only be deleted by using GitLab either from the UI or API.
-This prevents accidentally deleting a branch through local Git commands or
-third-party Git clients.
-
-## Related topics
-
-- [Protected branches API](../../api/protected_branches.md)
-- [Branches](repository/branches/index.md)
-- [Branches API](../../api/branches.md)
-
-## Troubleshooting
-
-### Branch names are case-sensitive
-
-Branch names in `git` are case-sensitive. When configuring your protected branch,
-or your [target branch workflow](repository/branches/index.md#configure-workflows-for-target-branches),
-`dev` is not the same `DEV` or `Dev`.
+<!-- This redirect file can be deleted after <2024-12-12>. -->
+<!-- Redirects that point to other docs in the same project expire in three months. -->
+<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
+<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md
index 4042e2eb6f521fad203f9cc5b003ebd90b0d6fa9..a5e3cdddf1caccea48966e9a4fbda840940dca6d 100644
--- a/doc/user/project/protected_tags.md
+++ b/doc/user/project/protected_tags.md
@@ -21,7 +21,7 @@ Each rule allows you to match either:
- An individual tag name.
- Wildcards to control multiple tags at once.
-This feature evolved out of [protected branches](protected_branches.md).
+This feature evolved out of [protected branches](repository/branches/protected.md).
## Who can modify a protected tag
diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md
index 1a575b0f4632e8da4c7f2939384b9b0450db1d22..a1bd11eefaf6f9804507ae6595f6a257f8ad4e52 100644
--- a/doc/user/project/repository/branches/default.md
+++ b/doc/user/project/repository/branches/default.md
@@ -16,7 +16,7 @@ in the repository. A default branch has special configuration options not shared
by other branches:
- It cannot be deleted.
-- It's [initially protected](../../protected_branches.md) against
+- It's [initially protected](../../repository/branches/protected.md) against
forced pushes.
- When a merge request uses an
[issue closing pattern](../../issues/managing_issues.md#closing-issues-automatically)
@@ -102,7 +102,7 @@ DETAILS:
> - Full protection after initial push [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118729) in GitLab 16.0.
-GitLab administrators and group owners can define [branch protections](../../../project/protected_branches.md)
+GitLab administrators and group owners can define [branch protections](../../repository/branches/protected.md)
to apply to every repository's default branch
at the [instance level](#instance-level-default-branch-protection) and
[group level](#group-level-default-branch-protection) with one of the following options:
@@ -130,7 +130,7 @@ DETAILS:
This setting applies only to each repository's default branch. To protect other branches,
you must either:
-- Configure [branch protection in the repository](../../../project/protected_branches.md).
+- Configure [branch protection in the repository](../../repository/branches/protected.md).
- Configure [branch protection for groups](../../../group/manage.md#change-the-default-branch-protection-of-a-group).
Administrators of self-managed instances can customize the initial default branch protection for projects hosted on that instance. Individual
@@ -227,7 +227,7 @@ renames a Git repository's (`example`) default branch.
role and follow the instructions to
[change the default branch for this project](#change-the-default-branch-name-for-a-project).
Select `main` as your new default branch.
-1. Protect your new `main` branch as described in the [protected branches documentation](../../protected_branches.md).
+1. Protect your new `main` branch as described in the [protected branches documentation](../../repository/branches/protected.md).
1. Optional. If you want to delete the old default branch:
1. Verify that nothing is pointing to it.
1. Delete the branch on the remote:
diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md
index 963764b6a559c1dafaf893d084c938a1ee04f7e2..2c0d02b1d0ad76754f5f3609b8836e719fecaf20 100644
--- a/doc/user/project/repository/branches/index.md
+++ b/doc/user/project/repository/branches/index.md
@@ -149,7 +149,7 @@ Branch names with specific formatting offer extra benefits:
- Streamline your merge request workflow by
[prefixing branch names with issue numbers](#prefix-branch-names-with-issue-numbers).
-- Automate [branch protections](../../protected_branches.md) based on branch name.
+- Automate [branch protections](../../repository/branches/protected.md) based on branch name.
- Test branch names with [push rules](../push_rules.md) before branches are pushed up to GitLab.
- Define which [CI/CD jobs](../../../../ci/jobs/index.md) to run on merge requests.
@@ -198,7 +198,7 @@ GitLab provides multiple methods to protect individual branches. These methods
ensure your branches receive oversight and quality checks from their creation to their deletion:
- Apply enhanced security and protection to your project's [default branch](default.md).
-- Configure [protected branches](../../protected_branches.md) to:
+- Configure [protected branches](../../repository/branches/protected.md) to:
- Limit who can push and merge to a branch.
- Manage if users can force push to the branch.
- Manage if changes to files listed in the `CODEOWNERS` file can be pushed directly to the branch.
@@ -239,7 +239,7 @@ To view the **Branch rules overview** list:
- To view more information about protections on an existing branch:
1. Identify the branch you want more information about.
1. Select **View details** to see information about its:
- - [Branch protections](../../protected_branches.md).
+ - [Branch protections](../../repository/branches/protected.md).
- [Approval rules](../../merge_requests/approvals/rules.md#approvals-for-protected-branches).
- [Status checks](../../merge_requests/status_checks.md).
@@ -356,7 +356,7 @@ To compare branches in a repository:
Merged branches can be deleted in bulk if they meet all of these criteria:
-- They are not [protected branches](../../protected_branches.md).
+- They are not [protected branches](../../repository/branches/protected.md).
- They have been merged into the project's default branch.
Prerequisites:
@@ -442,7 +442,7 @@ To do this:
## Related topics
-- [Protected branches](../../protected_branches.md)
+- [Protected branches](../../repository/branches/protected.md)
- [Branches API](../../../../api/branches.md)
- [Protected Branches API](../../../../api/protected_branches.md)
- [Getting started with Git](../../../../topics/git/index.md)
diff --git a/doc/user/project/repository/branches/protected.md b/doc/user/project/repository/branches/protected.md
new file mode 100644
index 0000000000000000000000000000000000000000..13f2052156153e180a0ccebb7abdd8952d0a2d75
--- /dev/null
+++ b/doc/user/project/repository/branches/protected.md
@@ -0,0 +1,425 @@
+---
+stage: Create
+group: Source Code
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
+description: "Protected branches in GitLab restrict who can push to, merge, or modify a Git branch."
+---
+
+# Protected branches
+
+DETAILS:
+**Tier:** Free, Premium, Ultimate
+**Offering:** GitLab.com, Self-managed, GitLab Dedicated
+
+In GitLab, [permissions](../../../permissions.md) are fundamentally defined around the
+idea of having read or write permission to the repository and branches. To impose
+further restrictions on certain branches, they can be protected.
+
+A protected branch controls:
+
+- Which users can merge into the branch.
+- Which users can push to the branch.
+- If users can force push to the branch.
+- If changes to files listed in the CODEOWNERS file can be pushed directly to the branch.
+- Which users, groups, or access levels can unprotect the branch using the
+ [Protected branches API](../../../../api/protected_branches.md#update-a-protected-branch).
+- Which users can modify the branch with the [Commits API](../../../../api/commits.md).
+
+The [default branch](default.md) for your repository is protected by default.
+
+## Who can modify a protected branch
+
+> - Branch push permission [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118532) to require GitLab administrators to also have the **allowed** permission in GitLab 16.0.
+
+When a branch is protected, the default behavior enforces these restrictions on the branch.
+
+| Action | Who can do it |
+|:-------------------------|:----------------------------------------|
+| Protect a branch | At least the Maintainer role. |
+| Push to the branch | Anyone with **Allowed** permission. (1) |
+| Force push to the branch | No one. (3) |
+| Delete the branch | No one. (2) |
+
+1. Users with the Developer role can create a project in a group, but might not be allowed to
+ initially push to the [default branch](default.md).
+1. No one can delete a protected branch using Git commands, however, users with at least Maintainer
+ role can [delete a protected branch from the UI or API](#delete-a-protected-branch).
+1. If the `group_protected_branches` feature flag is enabled _and_ the same branch is
+ protected at both the group and project levels, force push settings configured
+ for that branch at the project level are ignored. All other protections continue
+ to use project level settings.
+
+You can implement a [merge request approval policy](../../../application_security/policies/merge_request_approval_policies.md#approval_settings)
+to prevent protected branches being unprotected or deleted.
+
+### When a branch matches multiple rules
+
+When a branch matches multiple rules, the **most permissive rule** determines the
+level of protection for the branch. For example, consider these rules, which include
+[wildcards](#protect-multiple-branches-with-wildcard-rules):
+
+| Branch name pattern | Allowed to merge | Allowed to push and merge |
+|---------------------|------------------------|---------------------------|
+| `v1.x` | Maintainer | Maintainer |
+| `v1.*` | Maintainer + Developer | Maintainer |
+| `v*` | No one | No one |
+
+A branch named `v1.x` is a case-sensitive match for all three branch name patterns: `v1.x`, `v1.*`, and `v*`.
+As the most permissive option determines the behavior, the resulting permissions for branch `v1.x` are:
+
+- **Allowed to merge:** Of the three settings, `Maintainer + Developer` is most permissive,
+ and controls branch behavior as a result. Even though the branch also matched `v1.x` and `v*`
+ (which each have stricter permissions), users with the Developer role can merge into the branch.
+- **Allowed to push and merge:** Of the three settings, `Maintainer` is the most permissive, and controls
+ branch behavior as a result. Even though branches matching `v*` are set to `No one`, branches
+ that _also_ match `v1.x` or `v1.*` receive the more permissive `Maintainer` permission.
+
+To be certain that a rule controls the behavior of a branch,
+_all_ other patterns that match must apply less or equally permissive rules.
+
+If you want to ensure that `No one` is allowed to push to branch `v1.x`, every pattern
+that matches `v1.x` must set `Allowed to push and merge` to `No one`, like this:
+
+| Branch name pattern | Allowed to merge | Allowed to push and merge |
+|---------------------|------------------------|---------------------------|
+| `v1.x` | Maintainer | No one |
+| `v1.*` | Maintainer + Developer | No one |
+| `v*` | No one | No one |
+
+### Set the default branch protection level
+
+Administrators can set a default branch protection level in the
+[**Admin** area](default.md#instance-level-default-branch-protection).
+
+## Add protection to existing branches
+
+Configure protected branches for all projects in a group, or just for a project.
+
+### For one project
+
+Prerequisites:
+
+- You must have at least the Maintainer role.
+- When granting a group **Allowed to merge** or **Allowed to push and merge** permissions
+ on a protected branch, the group must be added to the project.
+
+To protect a branch:
+
+1. On the left sidebar, select **Search or go to** and find your project.
+1. Select **Settings > Repository**.
+1. Expand **Protected branches**.
+1. Select **Add protected branch**.
+1. From the **Branch** dropdown list, select the branch you want to protect.
+1. From the **Allowed to merge** list, select a role that can merge into this branch.
+1. From the **Allowed to push and merge** list, select a role that can push to this branch.
+
+ NOTE:
+ In GitLab Premium and Ultimate, you can also add groups or individual users
+ to **Allowed to merge** and **Allowed to push and merge**.
+
+1. Select **Protect**.
+
+The protected branch displays in the list of protected branches.
+
+### For all projects in a group
+
+DETAILS:
+**Tier:** Premium, Ultimate
+**Offering:** Self-managed
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106532) in GitLab 15.9 [with a flag](../../../../administration/feature_flags.md) named `group_protected_branches`. Disabled by default.
+
+FLAG:
+On self-managed GitLab, by default this feature is not available.
+To make it available, an administrator can
+[enable the feature flag](../../../../administration/feature_flags.md)
+named `group_protected_branches`. On GitLab.com and GitLab Dedicated, this feature is not available.
+
+Group owners can create protected branches for a group. These settings are inherited
+by all projects in the group and can't be overridden by project settings. If a
+specific branch is configured with **Allowed to force push** settings at both the
+group and project levels, the **Allowed to force push** setting at the _project_ level
+is ignored in favor of the group level setting.
+
+Prerequisites:
+
+- You must have the Owner role for the group.
+
+To protect a branch for all the projects in a group:
+
+1. On the left sidebar, select **Search or go to** and find your group.
+1. Select **Settings > Repository**.
+1. Expand **Protected branches**.
+1. Select **Add protected branch**.
+1. In the **Branch** text box, type the branch name or a wildcard.
+ Branch names and wildcards [are case-sensitive](index.md#name-your-branch).
+1. From the **Allowed to merge** list, select a role that can merge into this branch.
+1. From the **Allowed to push and merge** list, select a role that can push to this branch.
+1. Select **Protect**.
+
+The protected branch is added to the list of protected branches.
+
+## Protect multiple branches with wildcard rules
+
+When using wildcards, multiple rules can apply to a single branch.
+If more than one rule applies to a branch, the _most permissive_ rule controls
+how the branch behaves. For merge controls to work properly, set
+**Allowed to push and merge** to a broader set of users than **Allowed to merge**.
+
+Prerequisites:
+
+- You must have at least the Maintainer role.
+
+To protect multiple branches at the same time:
+
+1. On the left sidebar, select **Search or go to** and find your project.
+1. Select **Settings > Repository**.
+1. Expand **Protected branches**.
+1. Select **Add protected branch**.
+1. From the **Branch** dropdown list, type the branch name and a wildcard.
+ Branch names and wildcards [are case-sensitive](index.md#name-your-branch). For example:
+
+ | Wildcard protected branch | Matching branches |
+ |---------------------------|--------------------------------------------------------|
+ | `*-stable` | `production-stable`, `staging-stable` |
+ | `production/*` | `production/app-server`, `production/load-balancer` |
+ | `*gitlab*` | `gitlab`, `gitlab/staging`, `master/gitlab/production` |
+
+1. From the **Allowed to merge** list, select a role that can merge into
+ this branch.
+1. From the **Allowed to push and merge** list, select a role that can
+ push to this branch. In GitLab Premium or Ultimate, you can also add groups or individual users.
+1. Select **Protect**.
+
+The protected branch displays in the list of protected branches.
+
+## Require everyone to submit merge requests for a protected branch
+
+You can force everyone to submit a merge request, rather than allowing them to
+check in directly to a protected branch:
+
+1. On the left sidebar, select **Search or go to** and find your project.
+1. Select **Settings > Repository**.
+1. Expand **Protected branches**.
+1. Select **Add protected branch**.
+1. From the **Branch** dropdown list, select the branch you want to protect.
+1. From the **Allowed to merge** list, select **Developers + Maintainers**.
+1. From the **Allowed to push and merge** list, select **No one**.
+1. Select **Protect**.
+
+Alternatively, you can [create](index.md#create-a-branch-rule) or [edit](index.md#edit-a-branch-rule) a branch rule. Then:
+
+1. Select **Edit** in the **Allowed to merge** section.
+1. Select **Developers and Maintainers**.
+1. Select **Save changes**.
+
+## Allow everyone to push directly to a protected branch
+
+You can allow everyone with write access to push to the protected branch.
+
+1. On the left sidebar, select **Search or go to** and find your project.
+1. Select **Settings > Repository**.
+1. Expand **Protected branches**.
+1. Select **Add protected branch**.
+1. From the **Branch** dropdown list, select the branch you want to protect.
+1. From the **Allowed to push and merge** list, select **Developers + Maintainers**.
+1. Select **Protect**.
+
+Alternatively, you can [create](index.md#create-a-branch-rule) or [edit](index.md#edit-a-branch-rule) a branch rule. Then:
+
+1. Select **Edit** in the **Allowed to push and merge** section.
+1. Select **Developers and Maintainers**.
+1. Select **Save changes**.
+
+## Allow deploy keys to push to a protected branch
+
+> - More restrictions on deploy keys [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/425926) in GitLab 16.5 [with a flag](../../../../administration/feature_flags.md) named `check_membership_in_protected_ref_access`. Disabled by default.
+
+You can push to a protected branch with a [deploy key](../../deploy_keys/index.md).
+
+Prerequisites:
+
+- The deploy key must be enabled for your project. A project deploy key is enabled by default when
+ it is created. However, a public deploy key must be
+ [granted](../../deploy_keys/index.md#grant-project-access-to-a-public-deploy-key) access to the
+ project.
+- The deploy key must have [write access](../../deploy_keys/index.md#permissions) to your project
+ repository.
+- The owner of the deploy key must have at least read access to the project.
+- If the `check_membership_in_protected_ref_access` feature flag is enabled, the owner of the
+ deploy key must also be a member of the project.
+
+To allow a deploy key to push to a protected branch:
+
+1. On the left sidebar, select **Search or go to** and find your project.
+1. Select **Settings > Repository**.
+1. Expand **Protected branches**.
+1. Select **Add protected branch**.
+1. From the **Branch** dropdown list, select the branch you want to protect.
+1. From the **Allowed to push and merge** list, select the deploy key.
+1. Select **Protect**.
+
+Deploy keys are not available in the **Allowed to merge** dropdown list.
+
+## Allow force push on a protected branch
+
+You can allow [force pushes](../../../../topics/git/git_rebase.md#force-pushing) to
+protected branches.
+
+To protect a new branch and enable force push:
+
+1. On the left sidebar, select **Search or go to** and find your project.
+1. Select **Settings > Repository**.
+1. Expand **Protected branches**.
+1. Select **Add protected branch**.
+1. From the **Branch** dropdown list, select the branch you want to protect.
+1. From the **Allowed to push and merge** and **Allowed to merge** lists, select the settings you want.
+1. To allow all users with push access to force push, turn on the **Allowed to force push** toggle.
+1. Select **Protect**.
+
+To enable force pushes on branches that are already protected:
+
+1. On the left sidebar, select **Search or go to** and find your project.
+1. Select **Settings > Repository**.
+1. Expand **Protected branches**.
+1. Select **Add protected branch**.
+1. In the list of protected branches, next to the branch, turn on the **Allowed to force push** toggle.
+
+Alternatively, you can [create](index.md#create-a-branch-rule) or [edit](index.md#edit-a-branch-rule) a branch rule. Then:
+
+1. In the list of protected branches, next to the branch, turn on the **Allowed to force push** toggle.
+
+Members who can push to this branch can now also force push.
+
+### When a branch matches multiple rules
+
+When a branch matches multiple rules, the **most permissive rule** determines the
+level of protection for the branch. For example, consider these rules, which include
+[wildcards](#protect-multiple-branches-with-wildcard-rules):
+
+| Branch name pattern | Allow force push |
+|---------------------|------------------|
+| `v1.x` | Yes |
+| `v1.*` | No |
+| `v*` | No |
+
+A branch named `v1.x` matches all three branch name patterns: `v1.x`, `v1.*`, and `v*`.
+As the most permissive option determines the behavior, the resulting permissions for branch `v1.x` are:
+
+- **Allow force push:** Of the three settings, `Yes` is most permissive,
+ and controls branch behavior as a result. Even though the branch also matched `v1.x` and `v*`
+ (which each have stricter permissions), any user that can push to this branch can also force push.
+
+NOTE:
+Force push settings for a branch at the project level are overridden by group level settings
+if the `group_protected_branches` feature flag is enabled and a group owner has set
+[group level protection for the same branch](#for-all-projects-in-a-group).
+
+## Require Code Owner approval on a protected branch
+
+DETAILS:
+**Tier:** Premium, Ultimate
+**Offering:** GitLab.com, Self-managed, GitLab Dedicated
+
+For a protected branch, you can require at least one approval by a [Code Owner](../../codeowners/index.md).
+If a branch is protected by multiple rules, code owner approval is required if _any_ of
+the applicable rules have **Required approval from code owners** enabled.
+
+To protect a new branch and enable Code Owner's approval:
+
+1. On the left sidebar, select **Search or go to** and find your project.
+1. Select **Settings > Repository**.
+1. Expand **Protected branches**.
+1. Select **Add protected branch**.
+1. From the **Branch** dropdown list, select the branch you want to protect.
+1. From the **Allowed to push and merge** and **Allowed to merge** lists, select the settings you want.
+1. Turn on the **Require approval from code owners** toggle.
+1. Select **Protect**.
+
+To enable Code Owner's approval on branches that are already protected:
+
+1. On the left sidebar, select **Search or go to** and find your project.
+1. Select **Settings > Repository**.
+1. Expand **Protected branches**.
+1. Select **Add protected branch**.
+1. In the list of protected branches, next to the branch, turn on the **Code owner approval** toggle.
+
+Alternatively, you can [create](index.md#create-a-branch-rule) or [edit](index.md#edit-a-branch-rule) a branch rule.
+Then, in the list of protected branches, next to the branch,
+turn on the **Code owner approval** toggle.
+
+When enabled, all merge requests for these branches require approval
+by a Code Owner per matched rule before they can be merged.
+Additionally, direct pushes to the protected branch are denied if a rule is matched.
+
+Any user who is not specified in the `CODEOWNERS` file cannot push
+changes for the specified files or paths, unless they are specifically allowed to.
+You don't have to restrict developers from pushing directly to the
+protected branch. Instead, you can restrict pushing to certain files where a review by
+Code Owners is required.
+
+In [GitLab Premium 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/35097), users and groups
+who are allowed to push to protected branches do not need a merge request to merge their feature branches.
+Thus, they can skip merge request approval rules, Code Owners included.
+
+## Run pipelines on protected branches
+
+The permission to merge or push to protected branches defines
+whether or not a user can run CI/CD pipelines and execute actions on jobs.
+
+Because [merge request pipelines](../../../../ci/pipelines/merge_request_pipelines.md) run on the source
+branch, a pipeline isn't created if the user opening a merge request does not have permission to merge
+or push to the source branch.
+
+See [Security on protected branches](../../../../ci/pipelines/index.md#pipeline-security-on-protected-branches)
+for details about the pipelines security model.
+
+## Create a new branch with protections
+
+Prerequisites:
+
+- You must have at least the Developer role.
+- To create a protected branch, branch protection must be configured to
+ [require everyone to submit merge requests for a protected branch](#require-everyone-to-submit-merge-requests-for-a-protected-branch).
+
+To create a new branch with protections:
+
+1. On the left sidebar, select **Search or go to** and find your project.
+1. Select **Code > Branches**.
+1. Select **New branch**.
+1. Fill in the branch name and select an existing branch, tag, or commit to
+ base the new branch on. If you [require everyone to submit merge requests for a protected branch](#require-everyone-to-submit-merge-requests-for-a-protected-branch), only existing protected branches and commits
+ that are already in protected branches are accepted.
+
+You can also use [the Branches API](../../../../api/branches.md) to create a branch with protections.
+
+If branch protection is configured to [allow everyone to push directly to a protected branch](#allow-everyone-to-push-directly-to-a-protected-branch), a branch with protections can also be created from the command line or a Git client application.
+
+## Delete a protected branch
+
+Users with at least the Maintainer role can manually delete protected
+branches by using the GitLab web interface:
+
+1. On the left sidebar, select **Search or go to** and find your project.
+1. Select **Code > Branches**.
+1. Next to the branch you want to delete, select **Delete** (**{remove}**).
+1. On the confirmation dialog, enter the branch name and select **Yes, delete protected branch**.
+ Branch names [are case-sensitive](index.md#name-your-branch).
+
+Protected branches can only be deleted by using GitLab either from the UI or API.
+This prevents accidentally deleting a branch through local Git commands or
+third-party Git clients.
+
+## Related topics
+
+- [Protected branches API](../../../../api/protected_branches.md)
+- [Branches](index.md)
+- [Branches API](../../../../api/branches.md)
+
+## Troubleshooting
+
+### Branch names are case-sensitive
+
+Branch names in `git` are case-sensitive. When configuring your protected branch,
+or your [target branch workflow](index.md#configure-workflows-for-target-branches),
+`dev` is not the same `DEV` or `Dev`.
diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md
index 91a183fe841268a4f90e1c6e9798d964459efa51..3d95d8de6e6884cd850c67ce33d39c855ff51089 100644
--- a/doc/user/project/repository/forking_workflow.md
+++ b/doc/user/project/repository/forking_workflow.md
@@ -74,7 +74,7 @@ or the command line. GitLab Premium and Ultimate tiers can also automate updates
Prerequisites:
-- The fork must be created from an [unprotected branch](../protected_branches.md) in upstream repository.
+- The fork must be created from an [unprotected branch](../repository/branches/protected.md) in upstream repository.
To update your fork from the GitLab UI:
diff --git a/doc/user/project/repository/mirror/bidirectional.md b/doc/user/project/repository/mirror/bidirectional.md
index ad94efccfaf123b333dd8d9008e9c49f99d235f5..04723d82755bfd4205c529632ef5aed4e74e2280 100644
--- a/doc/user/project/repository/mirror/bidirectional.md
+++ b/doc/user/project/repository/mirror/bidirectional.md
@@ -27,7 +27,7 @@ conflicts. Configure them to reduce conflicts, and how to settle them when they
- [Mirror only protected branches](index.md#mirror-only-protected-branches). Rewriting
any mirrored commit on either remote causes conflicts and mirroring to fail.
-- [Protect the branches](../../protected_branches.md) you want to mirror on both
+- [Protect the branches](../branches/protected.md) you want to mirror on both
remotes to prevent conflicts caused by rewriting history.
- Reduce mirroring delay with a [push event webhook](../../integrations/webhook_events.md#push-events).
Bidirectional mirroring creates a race condition where commits made close together
diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md
index 06ab8d5baf870f427e3afb6d22e50b044a8f3400..492a9102f600aaa2e87226c62c6684befdf15cf6 100644
--- a/doc/user/project/repository/mirror/index.md
+++ b/doc/user/project/repository/mirror/index.md
@@ -78,7 +78,7 @@ For more information, see [Get your SSH public key](#get-your-ssh-public-key).
### Mirror only protected branches
You can choose to mirror only the
-[protected branches](../../protected_branches.md) in the mirroring project,
+[protected branches](../branches/protected.md) in the mirroring project,
either from or to your remote repository. For [pull mirroring](pull.md),
non-protected branches in the mirroring project are not mirrored and can diverge.
diff --git a/doc/user/project/repository/mirror/troubleshooting.md b/doc/user/project/repository/mirror/troubleshooting.md
index 4cdf3c0507c5aabac96cb6b51265aeae370a1fb7..6247cdf980c17fe44e17abe43653e7fd923521a0 100644
--- a/doc/user/project/repository/mirror/troubleshooting.md
+++ b/doc/user/project/repository/mirror/troubleshooting.md
@@ -118,7 +118,7 @@ Pipelines might not run for multiple reasons:
being added to the pipeline.
- Pipelines are triggered using [the account that set up the pull mirror](https://gitlab.com/gitlab-org/gitlab/-/issues/13697).
If the account is no longer valid, pipelines do not run.
-- [Branch protection](../../protected_branches.md#run-pipelines-on-protected-branches)
+- [Branch protection](../../repository/branches/protected.md#run-pipelines-on-protected-branches)
might prevent the account that set up mirroring from running pipelines.
## `The repository is being updated`, but neither fails nor succeeds visibly
diff --git a/doc/user/project/repository/push_rules.md b/doc/user/project/repository/push_rules.md
index a10a7ec9d324fa65d15e76831851642367e3065b..697d3788e8413836c0f59ede48ff2cba20e23709 100644
--- a/doc/user/project/repository/push_rules.md
+++ b/doc/user/project/repository/push_rules.md
@@ -16,7 +16,7 @@ DETAILS:
Push rules are [pre-receive Git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) you
can enable in a user-friendly interface. Push rules give you more control over what
can and can't be pushed to your repository. While GitLab offers
-[protected branches](../protected_branches.md), you may need more specific rules, such as:
+[protected branches](../repository/branches/protected.md), you may need more specific rules, such as:
- Evaluating the contents of a commit.
- Confirming commit messages match expected formats.
@@ -293,7 +293,7 @@ to use them as standard characters in a match condition.
- [Signing commits with GPG](signed_commits/gpg.md)
- [Signing commits with SSH](signed_commits/ssh.md)
- [Signing commits with X.509](signed_commits/x509.md)
-- [Protected branches](../protected_branches.md)
+- [Protected branches](../repository/branches/protected.md)
- [Secret detection](../../application_security/secret_detection/index.md)
## Troubleshooting
diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md
index cc6216c763f3519cc13fbf825f755dedd2c7f420..6a83fff2859465bed92e27e844f1cb84ed648d79 100644
--- a/doc/user/project/repository/reducing_the_repo_size_using_git.md
+++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md
@@ -155,7 +155,7 @@ To purge files from a GitLab repository:
git push origin --force 'refs/heads/*'
```
- [Protected branches](../protected_branches.md) cause this to fail. To proceed, you must
+ [Protected branches](../repository/branches/protected.md) cause this to fail. To proceed, you must
remove branch protection, push, and then re-enable protected branches.
1. To remove large files from tagged releases, force push your changes to all tags on GitLab:
diff --git a/doc/user/project/settings/import_export_troubleshooting.md b/doc/user/project/settings/import_export_troubleshooting.md
index e0fdd30bb62dedfb690a3f3ec7e7277c1f671aef..a77c2ef9c10407af4d3eb1d4e4e490c0ad06ecb6 100644
--- a/doc/user/project/settings/import_export_troubleshooting.md
+++ b/doc/user/project/settings/import_export_troubleshooting.md
@@ -110,7 +110,7 @@ reduce the repository size for another import attempt:
use `git remote set-url origin <new-url> && git push --force --all`
to complete the import.
1. Update the imported repository's
- [branch protection rules](../protected_branches.md) and
+ [branch protection rules](../repository/branches/protected.md) and
its [default branch](../repository/branches/default.md), and
delete the temporary, `smaller-tmp-main` branch, and
the local, temporary data.
diff --git a/ee/app/assets/javascripts/security_orchestration/components/policy_editor/scan_result/lib/settings.js b/ee/app/assets/javascripts/security_orchestration/components/policy_editor/scan_result/lib/settings.js
index 8cf8f0a8116f0c234899df2115b9c3ee5544dcee..e52b7896f854d0b3945333d3283e3349edf02f34 100644
--- a/ee/app/assets/javascripts/security_orchestration/components/policy_editor/scan_result/lib/settings.js
+++ b/ee/app/assets/javascripts/security_orchestration/components/policy_editor/scan_result/lib/settings.js
@@ -99,7 +99,7 @@ export const SETTINGS_POPOVER_STRINGS = {
};
export const SETTINGS_LINKS = {
- [BLOCK_BRANCH_MODIFICATION]: helpPagePath('/user/project/protected_branches.html'),
+ [BLOCK_BRANCH_MODIFICATION]: helpPagePath('/user/project/repository/branches/protected.html'),
};
export const VALID_APPROVAL_SETTINGS = [
diff --git a/ee/app/assets/javascripts/security_orchestration/components/policy_editor/scan_result/settings/block_group_branch_modification.vue b/ee/app/assets/javascripts/security_orchestration/components/policy_editor/scan_result/settings/block_group_branch_modification.vue
index bcd2c7d331eb9219d3fc00bcdd7ab199521ec0bb..f228a229a9b3a95ede7cf94ef5a95b594897da7b 100644
--- a/ee/app/assets/javascripts/security_orchestration/components/policy_editor/scan_result/settings/block_group_branch_modification.vue
+++ b/ee/app/assets/javascripts/security_orchestration/components/policy_editor/scan_result/settings/block_group_branch_modification.vue
@@ -90,7 +90,7 @@ export default {
this.$emit('change', value);
},
},
- GROUP_PROTECTED_BRANCHES_DOCS: helpPagePath('user/project/protected_branches', {
+ GROUP_PROTECTED_BRANCHES_DOCS: helpPagePath('user/project/repository/branches/protected', {
anchor: 'for-all-projects-in-a-group',
}),
EXCEPTION_BRANCH_TYPE_TEXTS,
diff --git a/ee/app/views/projects/merge_requests/_code_owner_approval_rules.html.haml b/ee/app/views/projects/merge_requests/_code_owner_approval_rules.html.haml
index bbd4d0c36d612485344c462ea327f661e52e3553..df232a199563f56d8db66c57e9b6e04db7a9dacb 100644
--- a/ee/app/views/projects/merge_requests/_code_owner_approval_rules.html.haml
+++ b/ee/app/views/projects/merge_requests/_code_owner_approval_rules.html.haml
@@ -6,7 +6,7 @@
%strong= _('Code owner approval is required')
%p
= _('At least one approval from a code owner is required to change files matching the respective CODEOWNER rules.')
- = link_to(_('Read more'), help_page_path('user/project/protected_branches', anchor: 'require-code-owner-approval-on-a-protected-branch'))
+ = link_to(_('Read more'), help_page_path('user/project/repository/branches/protected', anchor: 'require-code-owner-approval-on-a-protected-branch'))
.border-bottom
%table.table.m-0
diff --git a/ee/app/views/shared/promotions/_promote_repository_features.html.haml b/ee/app/views/shared/promotions/_promote_repository_features.html.haml
index 1dfe524135d43e6e859dfafbe4727b484fc38bc7..8615ba227ffe513cbed31d40ae97749ee5078a26 100644
--- a/ee/app/views/shared/promotions/_promote_repository_features.html.haml
+++ b/ee/app/views/shared/promotions/_promote_repository_features.html.haml
@@ -19,7 +19,7 @@
= s_('Promotions|Repository Mirroring is a way to mirror repositories from external sources. It can be used to mirror all branches, tags, and commits that you have in your repository.')
- unless @project.feature_available?(:protected_refs_for_users)
%p
- = link_to s_('Promotions|Better Protected Branches'), help_page_path('user/project/protected_branches'), target: '_blank', rel: 'noopener noreferrer', class: 'gl-block'
+ = link_to s_('Promotions|Better Protected Branches'), help_page_path('user/project/repository/branches/protected'), target: '_blank', rel: 'noopener noreferrer', class: 'gl-block'
= s_('Promotions|You can restrict access to protected branches by choosing a role (Maintainers, Developers) as well as certain users.')
- c.with_primary_action do
diff --git a/ee/spec/frontend/security_orchestration/components/policy_editor/scan_result/settings/block_group_branch_modification_spec.js b/ee/spec/frontend/security_orchestration/components/policy_editor/scan_result/settings/block_group_branch_modification_spec.js
index c594e22745acb6377225ad30fa0679b32df4c2c1..65af528b477cf00aa39a94a40f72f326dbc9cf30 100644
--- a/ee/spec/frontend/security_orchestration/components/policy_editor/scan_result/settings/block_group_branch_modification_spec.js
+++ b/ee/spec/frontend/security_orchestration/components/policy_editor/scan_result/settings/block_group_branch_modification_spec.js
@@ -27,7 +27,7 @@ describe('BlockGroupBranchModification', () => {
it('renders the default', () => {
createComponent();
expect(findLink().attributes('href')).toBe(
- '/help/user/project/protected_branches#for-all-projects-in-a-group',
+ '/help/user/project/repository/branches/protected#for-all-projects-in-a-group',
);
expect(findExceptionDropdown().exists()).toBe(true);
expect(findExceptionDropdown().props('selected')).toBe(WITHOUT_EXCEPTIONS);
@@ -37,7 +37,7 @@ describe('BlockGroupBranchModification', () => {
it('renders when enabled', () => {
createComponent({ enabled: true });
expect(findLink().attributes('href')).toBe(
- '/help/user/project/protected_branches#for-all-projects-in-a-group',
+ '/help/user/project/repository/branches/protected#for-all-projects-in-a-group',
);
expect(findExceptionDropdown().exists()).toBe(true);
expect(findExceptionDropdown().props('selected')).toBe(WITHOUT_EXCEPTIONS);
diff --git a/spec/frontend/projects/settings/branch_rules/components/edit/protections/index_spec.js b/spec/frontend/projects/settings/branch_rules/components/edit/protections/index_spec.js
index 14edaf31a1febe94bc28683973d0a51874859a34..669f133eb62a5085fe558853e144023aa45f3234 100644
--- a/spec/frontend/projects/settings/branch_rules/components/edit/protections/index_spec.js
+++ b/spec/frontend/projects/settings/branch_rules/components/edit/protections/index_spec.js
@@ -32,7 +32,9 @@ describe('Branch Protections', () => {
it('renders help text', () => {
expect(findHelpText().text()).toMatchInterpolatedText(i18n.protectionsHelpText);
- expect(findHelpLink().attributes('href')).toBe('/help/user/project/protected_branches');
+ expect(findHelpLink().attributes('href')).toBe(
+ '/help/user/project/repository/branches/protected',
+ );
});
it('renders a PushProtections component with correct props', () => {
diff --git a/spec/frontend/projects/settings/components/branch_rule_modal_spec.js b/spec/frontend/projects/settings/components/branch_rule_modal_spec.js
index 54dc0881fc778e7aa40e60223448904aabf8100b..15e2b210ef53848edb8f710471cd9d59f556d38a 100644
--- a/spec/frontend/projects/settings/components/branch_rule_modal_spec.js
+++ b/spec/frontend/projects/settings/components/branch_rule_modal_spec.js
@@ -61,7 +61,7 @@ describe('BranchRuleModal', () => {
it('renders help link', () => {
expect(findHelpLink().attributes('href')).toBe(
- '/help/user/project/protected_branches#protect-multiple-branches-with-wildcard-rules',
+ '/help/user/project/repository/branches/protected#protect-multiple-branches-with-wildcard-rules',
);
});