Merge branch '15611-add-allow-force-push-toggle-docs' into 'master'

Add allow force push docs

See merge request gitlab-org/gitlab!55751

doc/user/project/protected_branches.md

@@ -35,7 +35,7 @@ See the [Changelog](#changelog) section for changes over time.
 ## Configuring protected branches
 
 To protect a branch, you need to have at least Maintainer permission level.
-The `master` branch is protected by default.
+The default branch for your repository is protected by default.
 
 1. In your project, go to **Settings > Repository**.
 1. Scroll to find the **Protected branches** section.
@@ -177,6 +177,41 @@ Deleting a protected branch is allowed only by using the web interface; not from
 This means that you can't accidentally delete a protected branch from your
 command line or a Git client application.
 
+## Allow force push on protected branches **(FREE SELF)**
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15611) in GitLab 13.10.
+> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default.
+> - It's disabled on GitLab.com.
+> - It's not recommended for production use.
+> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-allow-force-push-on-protected-branches).
+
+WARNING:
+This feature might not be available to you. Check the **version history** note above for details.
+
+You can allow force pushes to protected branches by either setting **Allow force push**
+when you protect a new branch, or by configuring an already-protected branch.
+
+To protect a new branch and enable Force push:
+
+1. Navigate to your project's **Settings > Repository**.
+1. Expand **Protected branches**, and scroll to **Protect a branch**.
+   ![Code Owners approval - new protected branch](img/code_owners_approval_new_protected_branch_v13_10.png)
+1. Select a **Branch** or wildcard you'd like to protect.
+1. Select the user levels **Allowed to merge** and **Allowed to push**.
+1. To allow all users with push access to force push, toggle the **Allow force push** slider.
+1. To reject code pushes that change files listed in the `CODEOWNERS` file, toggle
+   **Require approval from code owners**.
+1. Click **Protect**.
+
+To enable force pushes on branches already protected:
+
+1. Navigate to your project's **Settings > Repository**.
+1. Expand **Protected branches** and scroll to **Protected branch**.
+   ![Code Owners approval - branch already protected](img/code_owners_approval_protected_branch_v13_10.png)
+1. Toggle the **Allow force push** slider for the chosen branch.
+
+When enabled, members who are allowed to push to this branch can also force push.
+
 ## Protected branches approval by Code Owners **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in GitLab Premium 12.4.
@@ -193,14 +228,14 @@ To protect a new branch and enable Code Owner's approval:
 1. Scroll down to **Protect a branch**, select a **Branch** or wildcard you'd like to protect, select who's **Allowed to merge** and **Allowed to push**, and toggle the **Require approval from code owners** slider.
 1. Click **Protect**.
 
-![Code Owners approval - new protected branch](img/code_owners_approval_new_protected_branch_v12_4.png)
+![Code Owners approval - new protected branch](img/code_owners_approval_new_protected_branch_v13_10.png)
 
 To enable Code Owner's approval to branches already protected:
 
 1. Navigate to your project's **Settings > Repository** and expand **Protected branches**.
 1. Scroll down to **Protected branch** and toggle the **Code owner approval** slider for the chosen branch.
 
-![Code Owners approval - branch already protected](img/code_owners_approval_protected_branch_v12_4.png)
+![Code Owners approval - branch already protected](img/code_owners_approval_protected_branch_v13_10.png)
 
 When enabled, all merge requests targeting these branches require approval
 by a Code Owner per matched rule before they can be merged.
@@ -216,6 +251,25 @@ run CI/CD pipelines and execute actions on jobs that are related to those branch
 See [Security on protected branches](../../ci/pipelines/index.md#pipeline-security-on-protected-branches)
 for details about the pipelines security model.
 
+## Enable or disable allow force push on protected branches **(FREE SELF)**
+
+Allow force push on protected branches is under development and not ready for
+production use. It is deployed behind a feature flag that is **disabled by default**.
+[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md)
+can enable it.
+
+To enable it:
+
+```ruby
+Feature.enable(:allow_force_push_to_protected_branches)
+```
+
+To disable it:
+
+```ruby
+Feature.disable(:allow_force_push_to_protected_branches)
+```
+
 ## Changelog
 
 - **13.5**: [Allow Deploy keys to push to protected branches once more](https://gitlab.com/gitlab-org/gitlab/-/issues/30769).