From ec2a27f196c803fc0f6da7c92b2c49156b47af0a Mon Sep 17 00:00:00 2001
From: Brendan Lynch <blynch@gitlab.com>
Date: Wed, 11 Sep 2024 12:47:39 +0000
Subject: [PATCH] Apply 2 suggestion(s) to 1 file(s)
Co-authored-by: Amy Qualls <aqualls@gitlab.com>
---
.gitlab/CODEOWNERS | 2 +-
.../components/edit/branch_dropdown.vue | 2 +-
.../components/edit/protections/index.vue | 2 +-
.../branch_rules/components/view/index.vue | 2 +-
.../settings/components/branch_rule_modal.vue | 2 +-
.../shared/_create_protected_branch.html.haml | 4 +-
.../shared/_index.html.haml | 4 +-
.../16-0-source-code-branch-push.yml | 4 +-
data/whats_new/202102180001_13_09.yml | 2 +-
doc/administration/compliance.md | 2 +-
doc/api/branches.md | 4 +-
doc/api/group_protected_branches.md | 2 +-
doc/api/protected_branches.md | 6 +-
doc/ci/environments/deployment_safety.md | 2 +-
doc/ci/jobs/job_control.md | 2 +-
doc/ci/pipelines/index.md | 4 +-
doc/ci/pipelines/schedules.md | 2 +-
doc/ci/runners/configure_runners.md | 4 +-
doc/ci/secrets/hashicorp_vault.md | 4 +-
doc/ci/secrets/index.md | 2 +-
doc/ci/variables/index.md | 4 +-
doc/ci/variables/predefined_variables.md | 4 +-
doc/ci/yaml/index.md | 8 +-
doc/ci/yaml/workflow.md | 2 +-
.../hardening_cicd_recommendations.md | 2 +-
doc/security/hardening_nist_800_53.md | 2 +-
doc/security/information_exclusivity.md | 2 +-
doc/subscriptions/bronze_starter.md | 2 +-
doc/topics/git/git_rebase.md | 4 +-
doc/tutorials/scan_result_policy/index.md | 2 +-
doc/update/deprecations.md | 2 +-
.../merge_request_approval_policies.md | 2 +-
doc/user/clusters/agent/ci_cd_workflow.md | 2 +-
.../gitops/example_repository_structure.md | 2 +-
.../compliance/license_approval_policies.md | 2 +-
doc/user/group/import/migrated_items.md | 2 +-
doc/user/permissions.md | 10 +-
doc/user/project/codeowners/index.md | 2 +-
.../project/codeowners/troubleshooting.md | 2 +-
doc/user/project/deploy_keys/index.md | 6 +-
doc/user/project/import/github.md | 8 +-
.../project/merge_requests/approvals/rules.md | 6 +-
.../authorization_for_merge_requests.md | 4 +-
.../project/merge_requests/status_checks.md | 2 +-
doc/user/project/protected_branches.md | 428 +-----------------
doc/user/project/protected_tags.md | 2 +-
.../project/repository/branches/default.md | 8 +-
doc/user/project/repository/branches/index.md | 10 +-
.../project/repository/branches/protected.md | 425 +++++++++++++++++
.../project/repository/forking_workflow.md | 2 +-
.../repository/mirror/bidirectional.md | 2 +-
doc/user/project/repository/mirror/index.md | 2 +-
.../repository/mirror/troubleshooting.md | 2 +-
doc/user/project/repository/push_rules.md | 4 +-
.../reducing_the_repo_size_using_git.md | 2 +-
.../settings/import_export_troubleshooting.md | 2 +-
.../policy_editor/scan_result/lib/settings.js | 2 +-
.../block_group_branch_modification.vue | 2 +-
.../_code_owner_approval_rules.html.haml | 2 +-
.../_promote_repository_features.html.haml | 2 +-
.../block_group_branch_modification_spec.js | 4 +-
.../components/edit/protections/index_spec.js | 4 +-
.../components/branch_rule_modal_spec.js | 2 +-
63 files changed, 531 insertions(+), 518 deletions(-)
create mode 100644 doc/user/project/repository/branches/protected.md
diff --git a/.gitlab/CODEOWNERS b/.gitlab/CODEOWNERS
index 72056df92e159..8cf292fbf2bd5 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 6494456d56000..49ac035246485 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 bcc0f64d66736..95a6aac9cc867 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 3c3c8b4477b9e..323fe24866b54 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 dfadc4efbdadc..9a983575de019 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 4efb4196375e7..4998259df98fe 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 6ff5e30eefd82..ad62bc2977c76 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 ee32a486db1ad..424753823ec84 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 d6b4011f08963..b46a79ee1f2a0 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 5802eb6293399..8030a70ea31dc 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 49367c0b2f2e1..39e5229a5ff1d 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 99d411546356c..a389b292234b5 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 5a5f0cd9a619e..e12550d638838 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 e42cabbc51529..7cdeceb526a9b 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 d25c525c4dd35..83fd45daea998 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 1a3c0e79ec30a..d68a0804f70d2 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 25ddb52ec4ad1..e8119a5ff6fbb 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 891d9315b2a0c..e4efc307ef200 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 7b99d1c865e04..695021cdd868f 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 564d49611cd89..e699c696706bd 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 ee596f01da1b5..4fe5815a3f4b9 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 e0fa03bdf0b36..f3a8e0f43435b 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 ab0a84169cf2f..2b17430e86bf6 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 de5ad11d627c8..a783336c68986 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 72f3bc8e7b8d7..81260d2b6f8fa 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 7b1e1f8dee650..31e222a988948 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 8d0840a36f40b..d150305476dbe 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 824e7a2aa069f..a48f5b9ee9d87 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 52a993e83eca1..e5d5677f053bc 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 ba91e64f6938d..ee7cae4c82c17 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 7e99b5914a75b..b835e368d41cb 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 890da31496624..f5f44dea6e85b 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 4d31986fdb8cb..28b52f04ca28d 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 a181cfa28ee45..8088ac8e9142e 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 21d4e33ecb2c5..3986a3a9b0e3f 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 2a35602342da1..f5237bc2b1a21 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 4a2cdb1ba6d08..82f9d6fe61eaa 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 d1d0da52c86ed..a95b431e85597 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 cc7a9870853ff..c4f82730396fe 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 6a901fa6fdb69..f3f0aafc40406 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 b24e72c4e982f..4d1ef81c5242a 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 3fae41c9ff15a..4990b0e58fa19 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 e0acc194ec6fb..616f277fa1dda 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 3c0388ebd74d6..72154f3d89c57 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 23ce29f18f772..28eb87452fa0a 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 4042e2eb6f521..a5e3cdddf1cac 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 1a575b0f4632e..a1bd11eefaf6f 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 963764b6a559c..2c0d02b1d0ad7 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 0000000000000..13f2052156153
--- /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 91a183fe84126..3d95d8de6e688 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 ad94efccfaf12..04723d82755bf 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 06ab8d5baf870..492a9102f600a 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 4cdf3c0507c5a..6247cdf980c17 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 a10a7ec9d324f..697d3788e8413 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 cc6216c763f35..6a83fff285946 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 e0fdd30bb62de..a77c2ef9c1040 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 8cf8f0a8116f0..e52b7896f854d 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 bcd2c7d331eb9..f228a229a9b3a 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 bbd4d0c36d612..df232a199563f 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 1dfe524135d43..8615ba227ffe5 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 c594e22745acb..65af528b477cf 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 14edaf31a1feb..669f133eb62a5 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 54dc0881fc778..15e2b210ef538 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',
);
});
--
GitLab