Add latest changes from gitlab-org/gitlab@master

15 files changed, 366 insertions, 76 deletions

diff --git a/doc/api/groups.md b/doc/api/groups.md
index b3ab00b362e..cedfba4689f 100644
--- a/doc/api/groups.md
+++ b/doc/api/groups.md
@@ -769,7 +769,7 @@ Parameters:
 
 ### Options for `default_branch_protection`
 
-The `default_branch_protection` attribute determines whether developers and maintainers can push to the applicable master branch, as described in the following table:
+The `default_branch_protection` attribute determines whether developers and maintainers can push to the applicable [default branch](../user/project/repository/branches/default.md), as described in the following table:
 
 | Value | Description |
 |-------|-------------------------------------------------------------------------------------------------------------|
diff --git a/doc/api/projects.md b/doc/api/projects.md
index 46997a1e8ae..edd89bc34d5 100644
--- a/doc/api/projects.md
+++ b/doc/api/projects.md
@@ -1127,7 +1127,7 @@ POST /projects
 | `ci_config_path`                                            | string  | **{dotted-circle}** No | The path to CI configuration file. |
 | `container_expiration_policy_attributes`                    | hash    | **{dotted-circle}** No | Update the image cleanup policy for this project. Accepts: `cadence` (string), `keep_n` (integer), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean). |
 | `container_registry_enabled`                                | boolean | **{dotted-circle}** No | Enable container registry for this project. |
-| `default_branch`                                            | string  | **{dotted-circle}** No | `master` by default. |
+| `default_branch`                                            | string  | **{dotted-circle}** No | The [default branch](../user/project/repository/branches/default.md) name. |
 | `description`                                               | string  | **{dotted-circle}** No | Short project description. |
 | `emails_disabled`                                           | boolean | **{dotted-circle}** No | Disable email notifications. |
 | `external_authorization_classification_label` **(PREMIUM)** | string  | **{dotted-circle}** No | The classification label for the project. |
@@ -1276,7 +1276,7 @@ PUT /projects/:id
 | `ci_forward_deployment_enabled`                             | boolean        | **{dotted-circle}** No | When a new deployment job starts, [skip older deployment jobs](../ci/pipelines/settings.md#skip-outdated-deployment-jobs) that are still pending |
 | `container_expiration_policy_attributes`                    | hash           | **{dotted-circle}** No | Update the image cleanup policy for this project. Accepts: `cadence` (string), `keep_n` (integer), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean). |
 | `container_registry_enabled`                                | boolean        | **{dotted-circle}** No | Enable container registry for this project. |
-| `default_branch`                                            | string         | **{dotted-circle}** No | `master` by default. |
+| `default_branch`                                            | string         | **{dotted-circle}** No | The [default branch](../user/project/repository/branches/default.md) name. |
 | `description`                                               | string         | **{dotted-circle}** No | Short project description. |
 | `emails_disabled`                                           | boolean        | **{dotted-circle}** No | Disable email notifications. |
 | `external_authorization_classification_label` **(PREMIUM)** | string         | **{dotted-circle}** No | The classification label for the project. |
diff --git a/doc/development/changelog.md b/doc/development/changelog.md
index 98a3e75bb3c..2cabb447781 100644
--- a/doc/development/changelog.md
+++ b/doc/development/changelog.md
@@ -53,8 +53,8 @@ the `author` field. GitLab team members **should not**.
   a changelog entry regardless of these guidelines if the contributor wants one.
   Example: "Fixed a typo on the search results page."
 - Any docs-only changes **should not** have a changelog entry.
-- Any change behind a disabled feature flag **should not** have a changelog entry.
-- Any change behind an enabled feature flag **should** have a changelog entry.
+- Any change behind a feature flag **disabled** by default **should not** have a changelog entry.
+- Any change behind a feature flag that is **enabled** by default **should** have a changelog entry.
 - Any change that adds new usage data metrics and changes that needs to be documented in Product Intelligence [Event Dictionary](https://about.gitlab.com/handbook/product/product-intelligence-guide/#event-dictionary) **should** have a changelog entry.
 - A change that adds snowplow events **should** have a changelog entry -
 - A change that [removes a feature flag](feature_flags/index.md) **must** have a changelog entry.
diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md
index 2c084477152..90de72ce4b7 100644
--- a/doc/user/admin_area/settings/index.md
+++ b/doc/user/admin_area/settings/index.md
@@ -46,7 +46,7 @@ Access the default page for admin area settings by navigating to **Admin Area >
 
 | Option | Description |
 | ------ | ----------- |
-| [Repository's custom initial branch name](../../project/repository/branches/index.md#custom-initial-branch-name) | Set a custom branch name rather than master for all the new repositories created within your instance. |
+| [Repository's custom initial branch name](../../project/repository/branches/default.md#instance-level-custom-initial-branch-name) | Set a custom branch name for new repositories created in your instance. |
 | [Repository mirror](visibility_and_access_controls.md#allow-mirrors-to-be-set-up-for-projects) | Configure repository mirroring. |
 | [Repository storage](../../../administration/repository_storage_types.md) | Configure storage path settings. |
 | Repository maintenance | ([Repository checks](../../../administration/repository_checks.md) and [Housekeeping](../../../administration/housekeeping.md)). Configure automatic Git checks and housekeeping on repositories. |
diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md
index 46255755132..924b9b22e14 100644
--- a/doc/user/application_security/dast/index.md
+++ b/doc/user/application_security/dast/index.md
@@ -969,7 +969,9 @@ To edit an existing site profile:
 1. In the profile's row select the **More actions** (**{ellipsis_v}**) menu, then select **Edit**.
 1. Edit the fields then select **Save profile**.
 
-The site profile is updated with the edited details.
+If a site profile is linked to a security policy, a user cannot edit the profile from this page. See
+[Scan Policies](../policies/index.md)
+for more information.
 
 #### Delete a site profile
 
@@ -981,7 +983,9 @@ To delete an existing site profile:
 1. In the profile's row select the **More actions** (**{ellipsis_v}**) menu, then select **Delete**.
 1. Select **Delete** to confirm the deletion.
 
-The site profile is deleted.
+If a site profile is linked to a security policy, a user cannot delete the profile from this page.
+See [Scan Policies](../policies/index.md)
+for more information.
 
 #### Validate a site profile
 
@@ -1103,7 +1107,9 @@ To edit a scanner profile:
 1. Edit the form.
 1. Select **Save profile**.
 
-The scanner profile is updated with the edited details.
+If a scanner profile is linked to a security policy, a user cannot edit the profile from this page.
+See [Scan Policies](../policies/index.md)
+for more information.
 
 #### Delete a scanner profile
 
@@ -1115,7 +1121,9 @@ To delete a scanner profile:
 1. In the scanner's row select the **More actions** (**{ellipsis_v}**) menu, then select **Delete**.
 1. Select **Delete**.
 
-The scanner profile is deleted.
+If a scanner profile is linked to a security policy, a user cannot delete the profile from this
+page. See [Scan Policies](../policies/index.md)
+for more information.
 
 ## Reports
 
diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md
new file mode 100644
index 00000000000..33d792001e3
--- /dev/null
+++ b/doc/user/application_security/policies/index.md
@@ -0,0 +1,151 @@
+---
+stage: Protect
+group: Container Security
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+---
+
+# Scan Policies **(ULTIMATE)**
+
+> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5329) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10.
+> - Deployed behind a feature flag, disabled by default.
+> - Disabled on GitLab.com.
+
+Scan Policies in GitLab provide security teams a way to require scans of their choice to be run
+whenever a project pipeline runs according to the configuration specified. Security teams can
+therefore be confident that the scans they set up have not been changed, altered, or disabled. You
+can access these by navigating to your project's **Security & Compliance > Scan Policies** page.
+
+GitLab supports the following security policies:
+
+- [Scan Execution Policy](#scan-execution-policy-schema)
+
+WARNING:
+Scan Policies is under development and is not ready for production use. It's deployed behind a
+feature flag that's disabled by default.
+
+NOTE:
+We recommend using the [Security Policies project](#security-policies-project)
+exclusively for managing policies for the project. Do not add your application's source code to such
+projects.
+
+## Enable or disable scan policies
+
+Scan Policies is under development and is not ready for production use. It's deployed behind a
+feature flag that's disabled by default.
+[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md)
+can enable it for your instance. Scan Policies can be enabled or disabled per-project.
+
+To enable it:
+
+```ruby
+# Instance-wide
+Feature.enable(:security_orchestration_policies_configuration)
+# or by project
+Feature.enable(:security_orchestration_policies_configuration, Project.find(<project ID>))
+```
+
+To disable it:
+
+```ruby
+# Instance-wide
+Feature.disable(:security_orchestration_policies_configuration)
+# or by project
+Feature.disable(:security_orchestration_policies_configuration, Project.find(<project ID>))
+```
+
+## Security Policies project
+
+The Security Policies feature is a repository to store policies. All security policies are stored in
+the `.gitlab/security-policies` directory as a YAML file with this format:
+
+```yaml
+---
+type: scan_execution_policy
+name: Enforce DAST in every pipeline
+description: This policy enforces pipeline configuration to have a job with DAST scan
+enabled: true
+rules:
+- type: pipeline
+  branch: master
+actions:
+- scan: dast
+  scanner_profile: Scanner Profile A
+  site_profile: Site Profile B
+```
+
+### Scan Execution Policy Schema
+
+| Field | Type | Possible values | Description |
+|-------|------|-----------------|-------------|
+| `type` | `string` | `scan_execution_policy` | The policy's type. |
+| `name` | `string` |  | Name of the policy. |
+| `description` (optional) | `string` |  | Description of the policy. |
+| `enabled` | `boolean` | `true`, `false` | Flag to enable (`true`) or disable (`false`) the policy. |
+| `rules` | `array` of rules |  | List of rules that the policy applies. |
+| `actions` | `array` of actions |  | List of actions that the policy enforces. |
+
+### `pipeline` rule type
+
+This rule enforces the defined actions whenever the pipeline runs for a selected branch.
+
+| Field | Type | Possible values | Description |
+|-------|------|-----------------|-------------|
+| `type` | `string` | `pipeline` | The rule's type. |
+| `branch` | `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). |
+
+### `scan` action type
+
+This action executes the selected `scan` with additional parameters when conditions for at least one
+rule in the defined policy are met.
+
+| Field | Type | Possible values | Description |
+|-------|------|-----------------|-------------|
+| `scan` | `string` | `dast` | The action's type. |
+| `site_profile` | `string` | Name of the selected [DAST site profile](../dast/index.md#site-profile). | The DAST site profile to execute the DAST scan. |
+| `scanner_profile` | `string` or `null` | Name of the selected [DAST scanner profile](../dast/index.md#scanner-profile). | The DAST scanner profile to execute the DAST scan. |
+
+Note the following:
+
+- You must create the [site profile](../dast/index.md#site-profile) and [scanner profile](../dast/index.md#scanner-profile)
+  with selected names for the project that is assigned to the selected Security Policy Project.
+  Otherwise, the policy is not applied and a job with an error message is created instead.
+- Once you associate the site profile and scanner profile by name in the policy, it is not possible
+  to modify or delete them. If you want to modify them, you must first disable the policy by setting
+  the `active` flag to `false`.
+
+Here's an example:
+
+```yaml
+---
+type: scan_execution_policy
+name: Enforce DAST in every pipeline
+description: This policy enforces pipeline configuration to have a job with DAST scan
+enabled: true
+rules:
+- type: pipeline
+  branch: release/*
+actions:
+- scan: dast
+  scanner_profile: Scanner Profile A
+  site_profile: Site Profile B
+```
+
+In this example, the DAST scan runs with the scanner profile `Scanner Profile A` and the site
+profile `Site Profile B`. The scan runs for every pipeline executed on branches that match the
+`release/*` wildcard (for example, branch name `release/v1.2.1`).
+
+## Security Policy project selection
+
+When the Security Policy project is created and policies are created within that repository, you
+must create an association between that project and the project you want to apply policies to. To do
+this, navigate to your project's **Security & Compliance > Policies**, select
+**Security policy project** from the dropdown menu, then select the **Create policy** button to save
+changes.
+
+You can always change the **Security policy project** by navigating to your project's
+**Security & Compliance > Policies** and modifying the selected project.
+
+## Roadmap
+
+See the [Category Direction page](https://about.gitlab.com/direction/protect/container_network_security/)
+for more information on the product direction of Container Network Security.
diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md
index 8a2c40406e2..e5942aea754 100644
--- a/doc/user/application_security/security_dashboard/index.md
+++ b/doc/user/application_security/security_dashboard/index.md
@@ -152,7 +152,7 @@ found in those projects' default branches.
 ## Keeping the dashboards up to date
 
 The Security Dashboard displays information from the results of the most recent
-security scan on the [default branch](../../project/repository/branches/index.md#default-branch),
+security scan on the [default branch](../../project/repository/branches/default.md),
 which means that security scans are performed every time the branch is updated.
 
 If the default branch is updated infrequently, scans are run infrequently and the
diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md
index 9af339b20c6..38d95ccd0be 100644
--- a/doc/user/clusters/agent/index.md
+++ b/doc/user/clusters/agent/index.md
@@ -246,6 +246,10 @@ Replace the value of `agent-token` below with the token received from the previo
 docker run --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:latest generate --agent-token=your-agent-token --kas-address=wss://kas.gitlab.example.com --agent-version latest | kubectl apply -f -
 ```
 
+Set `agent-version` to the latest released patch version matching your
+GitLab installation's major and minor versions. For example, if you have
+GitLab v13.9.0, set `--agent-version=v13.9.1`.
+
 To find out the various options the above Docker container supports, run:
 
 ```shell
diff --git a/doc/user/group/index.md b/doc/user/group/index.md
index 58d2a97ba21..111cd2bf5c9 100644
--- a/doc/user/group/index.md
+++ b/doc/user/group/index.md
@@ -387,16 +387,10 @@ because the project cannot be moved.
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43290) in GitLab 13.6.
 
-By default, when you create a new project in GitLab, the initial branch is called `master`.
-For groups, a group owner can customize the initial branch name to something
-else. This way, every new project created under that group from then on starts from the custom branch name rather than `master`.
-
-To use a custom name for the initial branch:
-
-1. Go to the group's **Settings > Repository** page.
-1. Expand the **Default initial branch name** section.
-1. Change the default initial branch to a custom name of your choice.
-1. Select **Save changes**.
+When you create a new project in GitLab, a default branch is created with the
+first push. The group owner can
+[customize the initial branch](../project/repository/branches/default.md#group-level-custom-initial-branch-name)
+for the group's projects to meet your group's needs.
 
 ## Remove a group
 
@@ -467,7 +461,7 @@ For more information, [see this issue](https://gitlab.com/gitlab-org/gitlab/-/is
 
 To ensure only people from your organization can access particular
 resources, you can restrict access to groups by IP address. This setting applies to all subgroups,
-projects, issues, and so on. 
+projects, issues, and so on.
 
 IP access restrictions can be configured at the group level only.
 
diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md
index 42522723047..ef47ceadd88 100644
--- a/doc/user/group/repositories_analytics/index.md
+++ b/doc/user/group/repositories_analytics/index.md
@@ -69,7 +69,7 @@ For each day that a coverage report was generated by a job in a project's pipeli
 If the project's code coverage was calculated more than once in a day, we will take the last value from that day.
 
 NOTE:
-[In GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/270102), group code coverage data is taken from the configured [default branch](../../project/repository/branches/index.md#default-branch). In earlier versions, it is taken from the `master` branch.
+[In GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/270102), group code coverage data is taken from the configured [default branch](../../project/repository/branches/default.md). In earlier versions, it is taken from the `master` branch.
 
 <!-- ## Troubleshooting
 
diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md
index cfb22881431..4c79eb3ccbe 100644
--- a/doc/user/project/issues/managing_issues.md
+++ b/doc/user/project/issues/managing_issues.md
@@ -199,7 +199,7 @@ can be closed automatically when the commit reaches the project's default branch
 
 If a commit message or merge request description contains text matching a [defined pattern](#default-closing-pattern),
 all issues referenced in the matched text are closed. This happens when the commit
-is pushed to a project's [**default** branch](../repository/branches/index.md#default-branch),
+is pushed to a project's [**default** branch](../repository/branches/default.md),
 or when a commit or merge request is merged into it.
 
 For example, if `Closes #4, #6, Related to #5` is included in a Merge Request
diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md
index aef96ff12c9..73c7f0eb91f 100644
--- a/doc/user/project/protected_branches.md
+++ b/doc/user/project/protected_branches.md
@@ -26,7 +26,7 @@ By default, a protected branch does these things:
 - GitLab administrators are allowed to push to the protected branches.
 - Users with [Developer permissions](../permissions.md) are allowed to
   create a project in a group, but might not be allowed to initially
-  push to the [default branch](repository/branches/index.md#default-branch).
+  push to the [default branch](repository/branches/default.md).
 
 The default branch protection level is set in the [Admin Area](../admin_area/settings/visibility_and_access_controls.md#default-branch-protection).
 
diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md
new file mode 100644
index 00000000000..1363d883e76
--- /dev/null
+++ b/doc/user/project/repository/branches/default.md
@@ -0,0 +1,180 @@
+---
+stage: Create
+group: Source Code
+info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments"
+type: concepts, howto
+---
+
+# Default branch
+
+When you create a new [project](../../index.md), GitLab creates a default branch
+in the repository. A default branch has special configuration options not shared
+by other branches:
+
+- It's [initially protected](../../protected_branches.md#protected-branches) against
+  accidental deletion and forced pushes.
+- When a merge request uses an
+  [issue closing pattern](../../issues/managing_issues.md#closing-issues-automatically)
+  to close an issue, the work is merged into this branch.
+
+The name of your [new project's](../../index.md) default branch depends on any
+instance-level or group-level configuration changes made by your GitLab administrator.
+GitLab checks first for specific customizations, then checks at a broader level,
+using the GitLab default only if no customizations are set:
+
+1. A [project-specific](#change-the-default-branch-name-for-a-project) custom default branch name.
+1. A [subgroup-level](#group-level-custom-initial-branch-name) custom default branch name.
+1. A [group-level](#group-level-custom-initial-branch-name) custom default branch name.
+1. An [instance-level](#instance-level-custom-initial-branch-name) custom default branch name. **(FREE SELF)**
+1. If no custom default branch name is set at any level, GitLab defaults to:
+   - `main`: Projects created with GitLab 14.0 or later.
+   - `master`: Projects created before GitLab 14.0.
+
+In the GitLab UI, you can change the defaults at any level. GitLab also provides
+the [Git commands you need](#update-the-default-branch-name-in-your-repository) to update your copy of the repository.
+
+## Change the default branch name for a project
+
+To update the default branch name for an individual [project](../../index.md):
+
+1. Sign in to GitLab as a user with [Administrator](../../../permissions.md) permissions.
+1. In the left navigation menu, go to **Settings > Repository**.
+1. Expand **Default branch**, and select a new default branch.
+1. (Optional) Select the **Auto-close referenced issues on default branch** check box to close
+   issues when a merge request
+   [uses a closing pattern](../../issues/managing_issues.md#closing-issues-automatically).
+1. Select **Save changes**.
+
+API users can also use the `default_branch` attribute of the
+[Projects API](../../../../api/projects.md) when creating or editing a project.
+
+## Change the default branch name for an instance or group
+
+GitLab administrators can configure a new default branch name at the
+[instance level](#instance-level-custom-initial-branch-name) or
+[group level](#group-level-custom-initial-branch-name).
+
+### Instance-level custom initial branch name **(FREE SELF)**
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221013) in GitLab 13.2.
+> - It's deployed behind a feature flag, enabled by default.
+> - It cannot be enabled or disabled per-project.
+> - It's recommended for production use.
+> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-custom-initial-branch-name).
+
+GitLab [administrators](../../../permissions.md) of self-managed instances can
+customize the initial branch for projects hosted on that instance. Individual
+groups and subgroups can override this instance-wide setting for their projects.
+
+1. Go to **Admin Area > Settings > Repository**.
+1. Expand **Default initial branch name**.
+1. Change the default initial branch to a custom name of your choice.
+1. Select **Save changes**.
+
+Projects created on this instance after you change the setting use the
+custom branch name, unless a group-level or subgroup-level configuration
+overrides it.
+
+#### Enable or disable custom initial branch name **(FREE SELF)**
+
+Setting the default initial branch name is under development but ready for production use.
+It is deployed behind a feature flag that is **enabled by default**.
+[GitLab administrators with access to the GitLab Rails console](../../../../administration/feature_flags.md)
+can opt to disable it for your instance.
+
+To disable it:
+
+```ruby
+Feature.disable(:global_default_branch_name)
+```
+
+To enable it:
+
+```ruby
+Feature.enable(:global_default_branch_name)
+```
+
+### Group-level custom initial branch name **(FREE)**
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221014) in GitLab 13.6.
+
+Administrators of groups and subgroups can configure the default branch name for a group:
+
+1. Go to the group **Settings > Repository**.
+1. Expand **Default initial branch name**.
+1. Change the default initial branch to a custom name of your choice.
+1. Select **Save changes**.
+
+Projects created in this group after you change the setting use the custom branch name,
+unless a subgroup configuration overrides it.
+
+## Update the default branch name in your repository
+
+WARNING:
+Changing the name of your default branch can potentially break tests,
+CI/CD configuration, services, helper utilities, and any integrations your repository
+uses. Before you change this branch name, consult with your project owners and maintainers.
+Ensure they understand the scope of this change includes references to the old
+branch name in related code and scripts.
+
+When changing the default branch name for an existing repository, you should preserve
+the history of your default branch by renaming it, instead of deleting it. This example
+renames a Git repository's (`example`) default branch.
+
+1. On your local command line, navigate to your `example` repository, and ensure
+   you're on the default branch:
+
+   ```plaintext
+   cd example
+   git checkout master
+   ```
+
+1. Rename the existing default branch to the new name (`main`). The argument `-m`
+   transfers all commit history to the new branch:
+
+   ```plaintext
+   git branch -m master main
+   ```
+
+1. Push the newly created `main` branch upstream, and set your local branch to track
+   the remote branch with the same name:
+
+   ```plaintext
+   git push -u origin main
+   ```
+
+1. If you plan to remove the old default branch, update `HEAD` to point to your new default branch, `main`:
+
+   ```plaintext
+   git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main
+   ```
+
+1. Sign in to GitLab as an [administrator](../../../permissions.md) 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. (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:
+
+      ```plaintext
+      git push origin --delete master
+      ```
+
+      You can delete the branch at a later time, after you confirm the new default branch is working as expected.
+
+1. Notify your project contributors of this change, because they must also take some steps:
+
+   - Contributors should pull the new default branch to their local copy of the repository.
+   - Contributors with open merge requests that target the old default branch should manually
+     re-point the merge requests to use `main` instead.
+1. In your repository, update any references to the old branch name in your code.
+1. Update references to the old branch name in related code and scripts that reside outside
+   your repository, such as helper utilities and integrations.
+
+## Resources
+
+- [Discussion of default branch renaming](https://lore.kernel.org/git/pull.656.v4.git.1593009996.gitgitgadget@gmail.com/)
+  on the Git mailing list
+- [March 2021 blog post: The new Git default branch name](https://about.gitlab.com/blog/2021/03/10/new-git-default-branch-name/)
diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md
index d049b2108ee..66963fc1ea5 100644
--- a/doc/user/project/repository/branches/index.md
+++ b/doc/user/project/repository/branches/index.md
@@ -24,7 +24,9 @@ With [GitLab Starter](https://about.gitlab.com/pricing/), you can also request
 
 For more information on managing branches using the GitLab UI, see:
 
-- [Default branches](#default-branch)
+- [Default branches](default.md): When you create a new [project](../../index.md), GitLab creates a
+  default branch for the repository. You can change this setting at the project,
+  subgroup, group, or instance level.
 - [Create a branch](../web_editor.md#create-a-new-branch)
 - [Protected branches](../../protected_branches.md#protected-branches)
 - [Delete merged branches](#delete-merged-branches)
@@ -41,55 +43,6 @@ See also:
 - [GitLab Flow](../../../../university/training/gitlab_flow.md) documentation.
 - [Getting started with Git](../../../../topics/git/index.md) and GitLab.
 
-## Default branch
-
-When you create a new [project](../../index.md), GitLab sets `master` as the default
-branch of the repository. You can choose another branch to be your project's
-default under your project's **Settings > Repository**.
-
-When closing issues directly from merge requests through the [issue closing pattern](../../issues/managing_issues.md#closing-issues-automatically),
-the target is the project's **default branch**.
-
-The default branch is also initially [protected](../../protected_branches.md#protected-branches)
-against accidental deletion and forced pushes.
-
-### Custom initial branch name **(FREE SELF)**
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221013) in GitLab 13.2.
-> - It's deployed behind a feature flag, enabled by default.
-> - It's enabled on GitLab.com.
-> - It cannot be enabled or disabled per-project.
-> - It's recommended for production use.
-> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-custom-initial-branch-name). **(FREE SELF)**
-
-By default, when you create a new project in GitLab, the initial branch is called `master`.
-For self-managed instances, a GitLab administrator can customize the initial branch name to something
-else. This way, every new project created from then on starts from the custom branch name rather than `master`. To do so:
-
-1. Go to the **Admin Area > Settings > Repository** and expand **Default initial
-   branch name**.
-1. Change the default initial branch to a custom name of your choice.
-1. **Save Changes**.
-
-#### Enable or disable custom initial branch name **(FREE SELF)**
-
-Setting the default initial branch name is under development but ready for production use.
-It is deployed behind a feature flag that is **enabled by default**.
-[GitLab administrators with access to the GitLab Rails console](../../../../administration/feature_flags.md)
-can opt to disable it for your instance.
-
-To disable it:
-
-```ruby
-Feature.disable(:global_default_branch_name)
-```
-
-To enable it:
-
-```ruby
-Feature.enable(:global_default_branch_name)
-```
-
 ## Compare
 
 To compare branches in a repository:
diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md
index 785618a862a..73baab76c8e 100644
--- a/doc/user/project/settings/index.md
+++ b/doc/user/project/settings/index.md
@@ -21,7 +21,7 @@ functionality of a project.
 
 ### General project settings
 
-Adjust your project's name, description, avatar, [default branch](../repository/branches/index.md#default-branch), and topics:
+Adjust your project's name, description, avatar, [default branch](../repository/branches/default.md), and topics:
 
 ![general project settings](img/general_settings.png)