Add latest changes from gitlab-org/gitlab@master

48 files changed, 120 insertions, 127 deletions

diff --git a/doc/.vale/gitlab/Substitutions.yml b/doc/.vale/gitlab/Substitutions.yml
index b31bead3bcd..99d2eb1f11a 100644
--- a/doc/.vale/gitlab/Substitutions.yml
+++ b/doc/.vale/gitlab/Substitutions.yml
@@ -4,7 +4,7 @@
 # Checks for misused terms that should never be used at GitLab.
 # SubstitutionWarning.yml and SubstitionSuggestions.yml also exist.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://docs.errata.ai/vale/styles
 extends: substitution
 message: 'Use "%s" instead of "%s".'
 link: https://about.gitlab.com/handbook/communication/#top-misused-terms
diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md
index 9aa6bffdb98..fe4d991689a 100644
--- a/doc/administration/incoming_email.md
+++ b/doc/administration/incoming_email.md
@@ -469,11 +469,6 @@ This series of PowerShell commands enables [sub-addressing](#email-sub-addressin
 at the organization level in Office 365. This allows all mailboxes in the organization
 to receive sub-addressed mail:
 
-NOTE:
-This series of commands enables sub-addressing at the organization
-level in Office 365. This allows all mailboxes in the organization
-to receive sub-addressed mail.
-
 ```powershell
 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
 
diff --git a/doc/administration/monitoring/gitlab_self_monitoring_project/index.md b/doc/administration/monitoring/gitlab_self_monitoring_project/index.md
index 8d3c8555660..011340295fb 100644
--- a/doc/administration/monitoring/gitlab_self_monitoring_project/index.md
+++ b/doc/administration/monitoring/gitlab_self_monitoring_project/index.md
@@ -20,7 +20,8 @@ GitLab instance.
 
 All administrators at the time of creation of the project and group are
 added as maintainers of the group and project, and as an administrator, you can
-add new members to the group to give them maintainer access to the project.
+add new members to the group to give them the [Maintainer role](../../../user/permissions.md) for
+the project.
 
 This project is used to self monitor your GitLab instance. The metrics dashboard
 of the project shows some basic resource usage charts, such as CPU and memory usage
diff --git a/doc/administration/monitoring/performance/request_profiling.md b/doc/administration/monitoring/performance/request_profiling.md
index 15a58456e05..ebdca8d3960 100644
--- a/doc/administration/monitoring/performance/request_profiling.md
+++ b/doc/administration/monitoring/performance/request_profiling.md
@@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 To profile a request:
 
-1. Sign in to GitLab as a user with Administrator or Maintainer [permissions](../../../user/permissions.md).
+1. Sign in to GitLab as an Administrator or a user with the [Maintainer role](../../../user/permissions.md).
 1. In the navigation bar, click **Admin area**.
 1. Go to **Monitoring > Requests Profiles**.
 1. In the **Requests Profiles** section, copy the token.
diff --git a/doc/api/dependency_proxy.md b/doc/api/dependency_proxy.md
index 8448edef9c5..139669c018c 100644
--- a/doc/api/dependency_proxy.md
+++ b/doc/api/dependency_proxy.md
@@ -11,7 +11,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11631) in GitLab 12.10.
 > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to [GitLab Free](https://about.gitlab.com/pricing/) in GitLab 13.6.
 
-Deletes the cached manifests and blobs for a group. This endpoint requires group owner access.
+Deletes the cached manifests and blobs for a group. This endpoint requires the [Owner role](../user/permissions.md)
+for the group.
 
 WARNING:
 [A bug exists](https://gitlab.com/gitlab-org/gitlab/-/issues/277161) for this API.
diff --git a/doc/api/deploy_tokens.md b/doc/api/deploy_tokens.md
index ad144946445..c07ad5b4c07 100644
--- a/doc/api/deploy_tokens.md
+++ b/doc/api/deploy_tokens.md
@@ -49,7 +49,8 @@ Example response:
 
 ## Project deploy tokens
 
-Project deploy token API endpoints require project maintainer access or higher.
+Project deploy token API endpoints require the [Maintainer role](../user/permissions.md) or higher
+for the project.
 
 ### List project deploy tokens
 
diff --git a/doc/api/group_clusters.md b/doc/api/group_clusters.md
index ea7c13637c4..6853e38cc32 100644
--- a/doc/api/group_clusters.md
+++ b/doc/api/group_clusters.md
@@ -13,7 +13,7 @@ Similarly to [project-level](../user/project/clusters/index.md) and
 group-level Kubernetes clusters allow you to connect a Kubernetes cluster to
 your group, enabling you to use the same cluster across multiple projects.
 
-Users need at least [Maintainer](../user/permissions.md) access for the group to use these endpoints.
+Users need at least the [Maintainer role](../user/permissions.md) for the group to use these endpoints.
 
 ## List group clusters
 
diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md
index a431e754774..ab7ad241631 100644
--- a/doc/api/project_clusters.md
+++ b/doc/api/project_clusters.md
@@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23922) in GitLab 11.7.
 
-Users need at least [Maintainer](../user/permissions.md) access to use these endpoints.
+Users need at least the [Maintainer](../user/permissions.md) role to use these endpoints.
 
 ## List project clusters
 
diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md
index e5560360532..044e6bf5394 100644
--- a/doc/api/protected_branches.md
+++ b/doc/api/protected_branches.md
@@ -183,9 +183,9 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla
 | --------- | ---- | -------- | ----------- |
 | `id`                            | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
 | `name`                          | string         | yes | The name of the branch or wildcard |
-| `push_access_level`             | string         | no  | Access levels allowed to push (defaults: `40`, maintainer access level) |
-| `merge_access_level`            | string         | no  | Access levels allowed to merge (defaults: `40`, maintainer access level) |
-| `unprotect_access_level`        | string         | no  | Access levels allowed to unprotect (defaults: `40`, maintainer access level) |
+| `push_access_level`             | string         | no  | Access levels allowed to push (defaults: `40`, Maintainer role) |
+| `merge_access_level`            | string         | no  | Access levels allowed to merge (defaults: `40`, Maintainer role) |
+| `unprotect_access_level`        | string         | no  | Access levels allowed to unprotect (defaults: `40`, Maintainer role) |
 | `allow_force_push`              | boolean        | no  | Allow force push for all users with push access. (defaults: false) |
 | `allowed_to_push`               | array          | no  | **(PREMIUM)** Array of access levels allowed to push, with each described by a hash |
 | `allowed_to_merge`              | array          | no  | **(PREMIUM)** Array of access levels allowed to merge, with each described by a hash |
diff --git a/doc/api/protected_tags.md b/doc/api/protected_tags.md
index 63fa7183aab..e04f418258d 100644
--- a/doc/api/protected_tags.md
+++ b/doc/api/protected_tags.md
@@ -102,7 +102,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla
 | --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
 | `name` | string | yes | The name of the tag or wildcard |
-| `create_access_level` | string | no | Access levels allowed to create (defaults: `40`, maintainer access level) |
+| `create_access_level` | string | no | Access levels allowed to create (defaults: `40`, Maintainer role) |
 
 Example response:
 
diff --git a/doc/api/runners.md b/doc/api/runners.md
index 1f0209c3cae..9ac17515eb8 100644
--- a/doc/api/runners.md
+++ b/doc/api/runners.md
@@ -156,7 +156,8 @@ Example response:
 
 Get details of a runner.
 
-[Maintainer access or higher](../user/permissions.md) is required to get runner details at the project and group level.
+The [Maintainer role or higher](../user/permissions.md) is required to get runner details at the
+project and group level.
 
 Instance-level runner details via this endpoint are available to all signed in users.
 
diff --git a/doc/api/services.md b/doc/api/services.md
index e658c51f7e6..a743f153708 100644
--- a/doc/api/services.md
+++ b/doc/api/services.md
@@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 # Services API **(FREE)**
 
 NOTE:
-This API requires an access token with Maintainer or Owner permissions.
+This API requires an access token with the [Maintainer or Owner role](../user/permissions.md).
 
 ## List all active services
 
diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md
index df0bb2817ab..11365569268 100644
--- a/doc/ci/environments/protected_environments.md
+++ b/doc/ci/environments/protected_environments.md
@@ -23,8 +23,8 @@ with the right privileges can deploy to it, thus keeping it safe.
 NOTE:
 A GitLab admin is always allowed to use environments, even if they are protected.
 
-To protect, update, or unprotect an environment, you need to have at least
-[Maintainer permissions](../../user/permissions.md).
+To protect, update, or unprotect an environment, you need to have at least the
+[Maintainer role](../../user/permissions.md).
 
 ## Protecting environments
 
diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md
index b21bdb03b5b..552c007c70d 100644
--- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md
+++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md
@@ -45,7 +45,7 @@ pipeline for merged results.
 
 To enable pipelines for merge results:
 
-- You must have maintainer [permissions](../../../user/permissions.md).
+- You must have the [Maintainer role](../../../user/permissions.md).
 - You must be using [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) 11.9 or later.
 - You must not be using
   [fast forward merges](../../../user/project/merge_requests/fast_forward_merge.md) yet.
diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md
index 6a9714fe3cf..7f237655593 100644
--- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md
+++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md
@@ -70,7 +70,7 @@ branch](https://www.youtube.com/watch?v=D4qCqXgZkHQ).
 
 To enable merge trains:
 
-- You must have maintainer [permissions](../../../../user/permissions.md).
+- You must have the [Maintainer role](../../../../user/permissions.md).
 - You must be using [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) 11.9 or later.
 - In GitLab 13.0 and later, you need [Redis](https://redis.io/) 5.0 or later.
 - Your repository must be a GitLab repository, not an
diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md
index 0ad25f8af21..af6b9e5b6b3 100644
--- a/doc/ci/pipelines/index.md
+++ b/doc/ci/pipelines/index.md
@@ -229,7 +229,7 @@ This functionality is only available:
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24851) in GitLab 12.7.
 
-Users with [owner permissions](../../user/permissions.md) in a project can delete a pipeline
+Users with the [Owner role](../../user/permissions.md) in a project can delete a pipeline
 by clicking on the pipeline in the **CI/CD > Pipelines** to get to the **Pipeline Details**
 page, then using the **Delete** button.
 
diff --git a/doc/ci/quick_start/index.md b/doc/ci/quick_start/index.md
index 13c993d04fc..3b243a15b14 100644
--- a/doc/ci/quick_start/index.md
+++ b/doc/ci/quick_start/index.md
@@ -13,7 +13,7 @@ GitLab [continuous integration](https://about.gitlab.com/stages-devops-lifecycle
 Before you start, make sure you have:
 
 - A project in GitLab that you would like to use CI/CD for.
-- Maintainer or owner access for the project.
+- The [Maintainer or Owner role](../../user/permissions.md) for the project.
 
 If you are migrating from another CI/CD tool, view this documentation:
 
diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md
index 005bb1db057..edff51abda5 100644
--- a/doc/ci/runners/README.md
+++ b/doc/ci/runners/README.md
@@ -121,7 +121,8 @@ To enable shared runners:
 #### Disable shared runners
 
 You can disable shared runners for individual projects or for groups.
-You must have Owner permissions for the project or group.
+You must have the [Owner role](../../user/permissions.md#group-members-permissions) for the project
+or group.
 
 To disable shared runners for a project:
 
@@ -156,7 +157,7 @@ Group runners process jobs by using a first in, first out ([FIFO](https://en.wik
 #### Create a group runner
 
 You can create a group runner for your self-managed GitLab instance or for GitLab.com.
-You must have [Owner permissions](../../user/permissions.md#group-members-permissions) for the group.
+You must have the [Owner role](../../user/permissions.md#group-members-permissions) for the group.
 
 To create a group runner:
 
@@ -172,7 +173,7 @@ To create a group runner:
 
 You can view and manage all runners for a group, its subgroups, and projects.
 You can do this for your self-managed GitLab instance or for GitLab.com.
-You must have [Owner permissions](../../user/permissions.md#group-members-permissions) for the group.
+You must have the [Owner role](../../user/permissions.md#group-members-permissions) for the group.
 
 1. Go to the group where you want to view the runners.
 1. Go to **Settings > CI/CD** and expand the **Runners** section.
@@ -195,7 +196,7 @@ From this page, you can edit, pause, and remove runners from the group, its subg
 #### Pause or remove a group runner
 
 You can pause or remove a group runner for your self-managed GitLab instance or for GitLab.com.
-You must have [Owner permissions](../../user/permissions.md#group-members-permissions) for the group.
+You must have the [Owner role](../../user/permissions.md#group-members-permissions) for the group.
 
 1. Go to the group you want to remove or pause the runner for.
 1. Go to **Settings > CI/CD** and expand the **Runners** section.
@@ -225,7 +226,7 @@ A fork *does* copy the CI/CD settings of the cloned repository.
 #### Create a specific runner
 
 You can create a specific runner for your self-managed GitLab instance or for GitLab.com.
-You must have [Owner permissions](../../user/permissions.md#project-members-permissions) for the project.
+You must have the [Owner role](../../user/permissions.md#project-members-permissions) for the project.
 
 To create a specific runner:
 
@@ -239,7 +240,8 @@ To create a specific runner:
 A specific runner is available in the project it was created for. An administrator can
 enable a specific runner to apply to additional projects.
 
-- You must have Owner permissions for the project.
+- You must have the [Owner role](../../user/permissions.md#group-members-permissions) for the
+  project.
 - The specific runner must not be [locked](#prevent-a-specific-runner-from-being-enabled-for-other-projects).
 
 To enable or disable a specific runner for a project:
@@ -399,7 +401,8 @@ the GitLab instance. To determine this:
 ### Determine the IP address of a specific runner
 
 To can find the IP address of a runner for a specific project,
-you must have Owner [permissions](../../user/permissions.md#project-members-permissions) for the project.
+you must have the [Owner role](../../user/permissions.md#project-members-permissions) for the
+project.
 
 1. Go to the project's **Settings > CI/CD** and expand the **Runners** section.
 1. On the details page you should see a row for **IP Address**.
@@ -423,7 +426,7 @@ the appropriate dependencies to run Rails test suites.
 
 When you [register a runner](https://docs.gitlab.com/runner/register/), its default behavior is to **only pick**
 [tagged jobs](../yaml/README.md#tags).
-To change this, you must have Owner [permissions](../../user/permissions.md#project-members-permissions) for the project.
+To change this, you must have the [Owner role](../../user/permissions.md#project-members-permissions) for the project.
 
 To make a runner pick untagged jobs:
 
diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md
index bc8435afefd..7e5786b5e17 100644
--- a/doc/ci/variables/README.md
+++ b/doc/ci/variables/README.md
@@ -125,8 +125,8 @@ for [manually-triggered pipelines](../pipelines/index.md#run-a-pipeline-manually
 
 ### Project CI/CD variables
 
-You can add CI/CD variables to a project's settings. Only project members with
-[maintainer permissions](../../user/permissions.md#project-members-permissions)
+You can add CI/CD variables to a project's settings. Only project members with the
+[Maintainer role](../../user/permissions.md#project-members-permissions)
 can add or update project CI/CD variables. To keep a CI/CD variable secret, put it
 in the project settings, not in the `.gitlab-ci.yml` file.
 
diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md
index d379f775cc9..960d6af3657 100644
--- a/doc/development/documentation/styleguide/index.md
+++ b/doc/development/documentation/styleguide/index.md
@@ -1585,6 +1585,15 @@ elements:
 |:------------|:--------------------------------|:----------------------|
 | _go to_     | making a browser go to location | "navigate to", "open" |
 
+### Permissions vs roles
+
+GitLab users are [assigned roles](../../../user/permissions.md) that confer specific permissions:
+
+- _Maintainer_ is an example of a role.
+- _Create new issue_ is an example of a permission.
+
+[Do not use](#usage-list) these terms interchangeably.
+
 ## GitLab versions
 
 GitLab product documentation pages (not including [Contributor and Development](../../README.md)
diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md
index 8e2028532e4..de93e1d28c1 100644
--- a/doc/development/documentation/workflow.md
+++ b/doc/development/documentation/workflow.md
@@ -85,8 +85,8 @@ If you are a member of the GitLab Slack workspace, you can request help in `#doc
 
 ### Reviewing and merging
 
-Anyone with Maintainer access to the relevant GitLab project can merge documentation changes.
-Maintainers must make a good-faith effort to ensure that the content:
+Anyone with the [Maintainer role](../../user/permissions.md) to the relevant GitLab project can
+merge documentation changes. Maintainers must make a good-faith effort to ensure that the content:
 
 - Is clear and sufficiently easy for the intended audience to navigate and understand.
 - Meets the [Documentation Guidelines](index.md) and [Style Guide](styleguide/index.md).
diff --git a/doc/development/testing_guide/end_to_end/index.md b/doc/development/testing_guide/end_to_end/index.md
index e6da4771e55..9e1cbd3e04c 100644
--- a/doc/development/testing_guide/end_to_end/index.md
+++ b/doc/development/testing_guide/end_to_end/index.md
@@ -100,7 +100,8 @@ You may have noticed that we use `gitlab-org/build/omnibus-gitlab-mirror` instea
 This is due to technical limitations in the GitLab permission model: the ability to run a pipeline
 against a protected branch is controlled by the ability to push/merge to this branch.
 This means that for developers to be able to trigger a pipeline for the default branch in
-`gitlab-org/omnibus-gitlab`/`gitlab-org/gitlab-qa`, they would need to have Maintainer permission in those projects.
+`gitlab-org/omnibus-gitlab`/`gitlab-org/gitlab-qa`, they would need to have the 
+[Maintainer role](../../../user/permissions.md) for those projects.
 For security reasons and implications, we couldn't open up the default branch to all the Developers.
 Hence we created these mirrors where Developers and Maintainers are allowed to push/merge to the default branch.
 This problem was discovered in <https://gitlab.com/gitlab-org/gitlab-qa/-/issues/63#note_107175160> and the "mirror"
diff --git a/doc/operations/incident_management/incidents.md b/doc/operations/incident_management/incidents.md
index d09dbd2cb04..849f2fdbb02 100644
--- a/doc/operations/incident_management/incidents.md
+++ b/doc/operations/incident_management/incidents.md
@@ -69,7 +69,7 @@ You can set up a webhook with PagerDuty to automatically create a GitLab inciden
 for each PagerDuty incident. This configuration requires you to make changes
 in both PagerDuty and GitLab:
 
-1. Sign in as a user with Maintainer [permissions](../../user/permissions.md).
+1. Sign in as a user with the [Maintainer role](../../user/permissions.md).
 1. Navigate to **Settings > Operations > Incidents** and expand **Incidents**.
 1. Select the **PagerDuty integration** tab:
 
diff --git a/doc/operations/incident_management/integrations.md b/doc/operations/incident_management/integrations.md
index 92fde29624c..f76a5befa27 100644
--- a/doc/operations/incident_management/integrations.md
+++ b/doc/operations/incident_management/integrations.md
@@ -18,7 +18,7 @@ to use this endpoint.
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/245331) in GitLab Free 13.5.
 
-With Maintainer or higher [permissions](../../user/permissions.md),
+With the [Maintainer role or higher](../../user/permissions.md),
 you can view the list of configured alerts integrations by navigating to **Settings > Operations**
 in your project's sidebar menu, and expanding the **Alerts** section. The list displays
 the integration name, type, and status (enabled or disabled):
@@ -219,7 +219,7 @@ active at the same time.
 
 To enable Opsgenie integration:
 
-1. Sign in as a user with Maintainer or Owner [permissions](../../user/permissions.md).
+1. Sign in as a user with the [Maintainer or Owner role](../../user/permissions.md).
 1. Navigate to **Operations > Alerts**.
 1. In the **Integrations** select box, select **Opsgenie**.
 1. Select the **Active** toggle.
diff --git a/doc/topics/git/lfs/index.md b/doc/topics/git/lfs/index.md
index ff5cfe0ac3e..dfb175cbb82 100644
--- a/doc/topics/git/lfs/index.md
+++ b/doc/topics/git/lfs/index.md
@@ -114,11 +114,9 @@ See the documentation on [File Locking](../../../user/project/file_lock.md).
 ## LFS objects in project archives
 
 > - Support for including Git LFS blobs inside [project source downloads](../../../user/project/repository/index.md) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5.
-> - [Deployed behind a feature flag](../../../user/feature_flags.md), disabled by default.
 > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/268409) in GitLab 13.6.
 > - Enabled on GitLab.com.
 > - Recommended for production use.
-> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-lfs-objects-in-project-archives).
 
 WARNING:
 This feature might not be available to you. Check the **version history** note above for details.
@@ -134,31 +132,11 @@ oid sha256:3ea5dd307f195f449f0e08234183b82e92c3d5f4cff11c2a6bb014f9e0de12aa
 size 177735
 ```
 
-Starting with GitLab 13.5, these pointers are converted to the uploaded
-LFS object if the `include_lfs_blobs_in_archive` feature flag is
-enabled.
+In GitLab version 13.5 and later, these pointers are converted to the uploaded
+LFS object.
 
 Technical details about how this works can be found in the [development documentation for LFS](../../../development/lfs.md#including-lfs-blobs-in-project-archives).
 
-### Enable or disable LFS objects in project archives
-
-_LFS objects in project archives_ 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.
-
-To enable it:
-
-```ruby
-Feature.enable(:include_lfs_blobs_in_archive)
-```
-
-To disable it:
-
-```ruby
-Feature.disable(:include_lfs_blobs_in_archive)
-```
-
 ## Troubleshooting
 
 ### Encountered `n` file(s) that should have been pointers, but weren't
diff --git a/doc/topics/git/lfs/migrate_to_git_lfs.md b/doc/topics/git/lfs/migrate_to_git_lfs.md
index 3f8e0575add..d31f329f8c3 100644
--- a/doc/topics/git/lfs/migrate_to_git_lfs.md
+++ b/doc/topics/git/lfs/migrate_to_git_lfs.md
@@ -41,7 +41,7 @@ Before beginning, make sure:
 
 To follow this tutorial, you need:
 
-- Maintainer permissions to the existing Git repository
+- The [Maintainer role](../../../user/permissions.md) for the existing Git repository
   you'd like to migrate to LFS with access through the command line.
 - [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
   and [Java Runtime Environment](https://www.java.com/en/download/manual.jsp)
diff --git a/doc/topics/gitlab_flow.md b/doc/topics/gitlab_flow.md
index ea81d544638..df5029bb0d1 100644
--- a/doc/topics/gitlab_flow.md
+++ b/doc/topics/gitlab_flow.md
@@ -152,7 +152,8 @@ After the assigned person feels comfortable with the result, they can merge the
 If the assigned person does not feel comfortable, they can request more changes or close the merge request without merging.
 
 In GitLab, it is common to protect the long-lived branches, such as the `main` branch, so [most developers can't modify them](../user/permissions.md).
-So, if you want to merge into a protected branch, assign your merge request to someone with maintainer permissions.
+So, if you want to merge into a protected branch, assign your merge request to someone with the 
+[Maintainer role](../user/permissions.md).
 
 After you merge a feature branch, you should remove it from the source control software.
 In GitLab, you can do this when merging.
diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md
index fd4eb01b98a..cf57afb8324 100644
--- a/doc/user/discussions/index.md
+++ b/doc/user/discussions/index.md
@@ -26,7 +26,7 @@ when it receives a reply.
 The comment area supports [Markdown](../markdown.md) and [quick actions](../project/quick_actions.md).
 You can [suggest code changes](../project/merge_requests/reviews/suggestions.md) in your comment,
 which the user can accept through the user interface. You can edit your own
-comment at any time, and anyone with [Maintainer access level](../permissions.md) or
+comment at any time, and anyone with the [Maintainer role](../permissions.md) or
 higher can also edit a comment made by someone else.
 
 You can also reply to a comment notification email to reply to the comment if
diff --git a/doc/user/group/index.md b/doc/user/group/index.md
index 5788975f42c..69826acd458 100644
--- a/doc/user/group/index.md
+++ b/doc/user/group/index.md
@@ -79,7 +79,7 @@ You can give a user access to all projects in a group.
 1. Find your group and select it.
 1. From the left sidebar, select **Members**.
 1. Fill in the fields.
-   - The role applies to all projects in the group. [Learn more about permissions](../permissions.md#permissions).
+   - The role applies to all projects in the group. [Learn more about permissions](../permissions.md).
    - On the **Access expiration date**, the user can no longer access projects in the group.
 
 ## Request access to a group
@@ -111,22 +111,22 @@ your group.
 ## Change the owner of a group
 
 You can change the owner of a group. Each group must always have at least one
-member with [Owner permission](../permissions.md#group-members-permissions).
+member with the [Owner role](../permissions.md#group-members-permissions).
 
 - As an administrator:
   1. Go to the group and from the left menu, select **Members**.
-  1. Give a different member **Owner** permissions.
-  1. Refresh the page. You can now remove **Owner** permissions from the original owner.
+  1. Give a different member the **Owner** role.
+  1. Refresh the page. You can now remove the **Owner** role from the original owner.
 - As the current group's owner:
   1. Go to the group and from the left menu, select **Members**.
-  1. Give a different member **Owner** permissions.
-  1. Have the new owner sign in and remove **Owner** permissions from you.
+  1. Give a different member the **Owner** role.
+  1. Have the new owner sign in and remove the **Owner** role from you.
 
 ## Remove a member from the group
 
 Prerequisites:
 
-- You must have [Owner permissions](../permissions.md#group-members-permissions).
+- You must have the [Owner role](../permissions.md#group-members-permissions).
 - The member must have direct membership in the group. If
   membership is inherited from a parent group, then the member can be removed
   from the parent group only.
diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md
index df0d297a82a..14b4475dda9 100644
--- a/doc/user/group/subgroups/index.md
+++ b/doc/user/group/subgroups/index.md
@@ -163,7 +163,7 @@ added to), add the user to the new subgroup again with a higher set of permissio
 
 For example, if User 1 was first added to group `one/two` with Developer
 permissions, then they inherit those permissions in every other subgroup
-of `one/two`. To give them Maintainer access to group `one/two/three/four`,
+of `one/two`. To give them the [Maintainer role](../../permissions.md) for group `one/two/three/four`,
 you would add them again in that group as Maintainer. Removing them from that group,
 the permissions fall back to those of the ancestor group.
 
diff --git a/doc/user/infrastructure/terraform_state.md b/doc/user/infrastructure/terraform_state.md
index 2cd5ed8ac78..90858f9be8d 100644
--- a/doc/user/infrastructure/terraform_state.md
+++ b/doc/user/infrastructure/terraform_state.md
@@ -28,10 +28,10 @@ before using this feature.
 
 ## Permissions for using Terraform
 
-In GitLab version 13.1, [Maintainer access](../permissions.md) was required to use a
-GitLab managed Terraform state backend. In GitLab versions 13.2 and greater,
-[Maintainer access](../permissions.md) is required to lock, unlock and write to the state
-(using `terraform apply`), while [Developer access](../permissions.md) is required to read
+In GitLab version 13.1, the [Maintainer role](../permissions.md) was required to use a
+GitLab managed Terraform state backend. In GitLab versions 13.2 and greater, the
+[Maintainer role](../permissions.md) is required to lock, unlock, and write to the state
+(using `terraform apply`), while the [Developer role](../permissions.md) is required to read
 the state (using `terraform plan -lock=false`).
 
 ## Set up GitLab-managed Terraform state
@@ -351,8 +351,8 @@ location. You can then go back to running it in GitLab CI/CD.
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/273592) in GitLab 13.8.
 
 Users with Developer and greater [permissions](../permissions.md) can view the
-state files attached to a project at **Operations > Terraform**. Users with
-Maintainer permissions can perform commands on the state files. The user interface
+state files attached to a project at **Operations > Terraform**. Users with the
+Maintainer role can perform commands on the state files. The user interface
 contains these fields:
 
 ![Terraform state list](img/terraform_list_view_v13_8.png)
diff --git a/doc/user/permissions.md b/doc/user/permissions.md
index 245efc0e908..d73e377e771 100644
--- a/doc/user/permissions.md
+++ b/doc/user/permissions.md
@@ -4,11 +4,11 @@ group: Access
 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
 ---
 
-# Permissions
+# Permissions and roles
 
-Users have different abilities depending on the access level they have in a
+Users have different abilities depending on the role they have in a
 particular group or project. If a user is both in a project's group and the
-project itself, the highest permission level is used.
+project itself, the highest role is used.
 
 On public and internal projects, the Guest role is not enforced. All users can:
 
@@ -39,11 +39,11 @@ usernames. A GitLab administrator can configure the GitLab instance to
 NOTE:
 In GitLab 11.0, the Master role was renamed to Maintainer.
 
-The Owner permission is only available at the group or personal namespace level (and for instance administrators) and is inherited by its projects.
+The Owner role is only available at the group or personal namespace level (and for instance administrators) and is inherited by its projects.
 While Maintainer is the highest project-level role, some actions can only be performed by a personal namespace or group owner, or an instance administrator, who receives all permissions.
 For more information, see [projects members documentation](project/members/index.md).
 
-The following table depicts the various user permission levels in a project.
+The following table lists project permissions available for each role:
 
 | Action                                            | Guest   | Reporter   | Developer   |Maintainer| Owner  |
 |---------------------------------------------------|---------|------------|-------------|----------|--------|
@@ -256,8 +256,9 @@ NOTE:
 In GitLab 11.0, the Master role was renamed to Maintainer.
 
 Any user can remove themselves from a group, unless they are the last Owner of
-the group. The following table depicts the various user permission levels in a
-group.
+the group.
+
+The following table lists group permissions available for each role:
 
 | Action                                                 | Guest | Reporter | Developer | Maintainer | Owner |
 |--------------------------------------------------------|-------|----------|-----------|------------|-------|
diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md
index f9c563a38b9..e61299ec6f3 100644
--- a/doc/user/project/clusters/add_remove_clusters.md
+++ b/doc/user/project/clusters/add_remove_clusters.md
@@ -35,9 +35,9 @@ Before [adding a Kubernetes cluster](#create-new-cluster) using GitLab, you need
   - A [self-managed installation](https://about.gitlab.com/pricing/#self-managed) with GitLab version
     12.5 or later. This ensures the GitLab UI can be used for cluster creation.
 - The following GitLab access:
-  - [Maintainer access to a project](../../permissions.md#project-members-permissions) for a
+  - [Maintainer role for a project](../../permissions.md#project-members-permissions) for a
     project-level cluster.
-  - [Maintainer access to a group](../../permissions.md#group-members-permissions) for a
+  - [Maintainer role for a group](../../permissions.md#group-members-permissions) for a
     group-level cluster.
   - [Admin Area access](../../admin_area/index.md) for a self-managed instance-level
     cluster. **(FREE SELF)**
diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md
index a6b54474a9e..c0bc97781b6 100644
--- a/doc/user/project/deploy_keys/index.md
+++ b/doc/user/project/deploy_keys/index.md
@@ -28,7 +28,7 @@ repository in automation, it's a simple solution.
 A drawback is that your repository could become vulnerable if a remote machine is compromised
 by a hacker. You should limit access to the remote machine before a deploy key is
 enabled on your repository. A good rule to follow is to provide access only to trusted users,
-and make sure that the allowed users have [maintainer permissions or higher](../../permissions.md)
+and make sure that the allowed users have the [Maintainer role or higher](../../permissions.md)
 in the GitLab project.
 
 If this security implication is a concern for your organization,
diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md
index 4c93947d5a0..eb963cb74c5 100644
--- a/doc/user/project/file_lock.md
+++ b/doc/user/project/file_lock.md
@@ -80,7 +80,7 @@ Check this document to learn more about [using Git LFS](../../topics/git/lfs/ind
 
 ### Configure Exclusive File Locks
 
-You need [Maintainer permissions](../permissions.md) to configure
+You need the [Maintainer role](../permissions.md) to configure
 Exclusive File Locks for your project through the command line.
 
 The first thing to do before using File Locking is to tell Git LFS which
@@ -226,6 +226,6 @@ who locked the file.
 
 The **Locked Files**, accessed from **Project > Repository** left menu, lists
 all file and directory locks. Locks can be removed by their author, or any user
-with Maintainer permissions and above.
+with the [Maintainer role](../permissions.md) and above.
 
 This list shows all the files locked either through LFS or GitLab UI.
diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md
index c7772ac2238..f9e15ced858 100644
--- a/doc/user/project/integrations/index.md
+++ b/doc/user/project/integrations/index.md
@@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 You can find the available integrations under your project's
 **Settings > Integrations** page. You need to have at least
-[maintainer permission](../../permissions.md) on the project.
+the [Maintainer role](../../permissions.md) on the project.
 
 ## Integrations
 
diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md
index 25357a1db0b..ed15d7a2e63 100644
--- a/doc/user/project/issues/confidential_issues.md
+++ b/doc/user/project/issues/confidential_issues.md
@@ -77,11 +77,11 @@ least [Reporter access](../../permissions.md#project-members-permissions). Howev
 confidential issues, but can only view the ones that they created themselves.
 
 Confidential issues are also hidden in search results for unprivileged users.
-For example, here's what a user with Maintainer and Guest access sees in the
-project's search results respectively.
+For example, here's what a user with the [Maintainer role](../../permissions.md) and Guest access
+sees in the project's search results respectively.
 
-| Maintainer access | Guest access |
-| :-----------: | :----------: |
+| Maintainer role                                                                        | Guest access                                                                     |
+|:---------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------|
 | ![Confidential issues search by maintainer](img/confidential_issues_search_master.png) | ![Confidential issues search by guest](img/confidential_issues_search_guest.png) |
 
 ## Merge Requests for Confidential Issues
diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md
index 869f6678640..35573518626 100644
--- a/doc/user/project/issues/managing_issues.md
+++ b/doc/user/project/issues/managing_issues.md
@@ -344,7 +344,7 @@ can change an issue's type. To do this, edit the issue and select an issue type
 
 ## Deleting issues
 
-Users with [project owner permission](../../permissions.md) can delete an issue by
+Users with the [Owner role](../../permissions.md) can delete an issue by
 editing it and selecting **Delete issue**.
 
 ![delete issue - button](img/delete_issue_v13_11.png)
diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md
index 7dc1a9c612f..d39c84e46f0 100644
--- a/doc/user/project/members/index.md
+++ b/doc/user/project/members/index.md
@@ -17,7 +17,7 @@ to perform actions.
 
 Prerequisite:
 
-- You must have maintainer or owner [permissions](../../permissions.md).
+- You must have the [Maintainer role or Owner role](../../permissions.md).
 
 To add a user to a project:
 
@@ -38,7 +38,7 @@ limited by the maximum role you choose when you invite the group.
 
 Prerequisite:
 
-- You must have maintainer or owner [permissions](../../permissions.md).
+- You must have the [Maintainer role or Owner role](../../permissions.md).
 
 To add groups to a project:
 
@@ -61,7 +61,7 @@ retain the same permissions as the project you import them from.
 
 Prerequisite:
 
-- You must have maintainer or owner [permissions](../../permissions.md).
+- You must have the [Maintainer role or Owner role](../../permissions.md).
 
 To import users:
 
@@ -87,7 +87,7 @@ From the image above, we can deduce the following things:
 - User1 is shown as a **Direct member** in the **Source** column, therefore they belong directly
   to the project we're inspecting.
 - Administrator is the Owner and member of **all** groups and for that reason,
-  there is an indication of an ancestor group and inherited Owner permissions.
+  there is an indication of an ancestor group and inherited the [Owner role](../../permissions.md).
 
 ## Filter and sort members
 
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 3a905c4d86d..930df65f3fc 100644
--- a/doc/user/project/merge_requests/authorization_for_merge_requests.md
+++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md
@@ -16,17 +16,17 @@ There are two main ways to have a merge request flow with GitLab:
 
 With the protected branch flow everybody works within the same GitLab project.
 
-The project maintainers get Maintainer access and the regular developers get
-Developer access.
+The project maintainers get the [Maintainer role](../../permissions.md) and the regular developers
+get Developer access.
 
-The maintainers mark the authoritative branches as 'Protected'.
+Maintainers mark the authoritative branches as 'Protected'.
 
-The developers push feature branches to the project and create merge requests
+Developers push feature branches to the project and create merge requests
 to have their feature branches reviewed and merged into one of the protected
 branches.
 
-By default, only users with Maintainer access can merge changes into a protected
-branch.
+By default, only users with the [Maintainer role](../../permissions.md) can merge changes into a
+protected branch.
 
 **Advantages**
 
@@ -39,7 +39,7 @@ branch.
 
 ## Forking workflow
 
-With the forking workflow the maintainers get Maintainer access and the regular
+With the forking workflow, maintainers get the [Maintainer role](../../permissions.md) and regular
 developers get Reporter access to the authoritative repository, which prohibits
 them from pushing any changes to it.
 
diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md
index 14c9e842b4b..ce39f39f0a1 100644
--- a/doc/user/project/merge_requests/getting_started.md
+++ b/doc/user/project/merge_requests/getting_started.md
@@ -153,7 +153,7 @@ enabled by default for all new merge requests, enable it in the
 
 This option is also visible in an existing merge request next to
 the merge request button and can be selected or deselected before merging.
-It is only visible to users with [Maintainer permissions](../../permissions.md)
+It is only visible to users with the [Maintainer role](../../permissions.md)
 in the source project.
 
 If the user viewing the merge request does not have the correct
diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md
index 673a756f18d..c3a674e17c0 100644
--- a/doc/user/project/protected_branches.md
+++ b/doc/user/project/protected_branches.md
@@ -36,7 +36,7 @@ The default branch protection level is set in the [Admin Area](../admin_area/set
 
 Prerequisite:
 
-- You must have at least maintainer permissions.
+- You must have at least the [Maintainer role](../permissions.md).
 
 To protect a branch:
 
@@ -163,7 +163,7 @@ To create a new branch through the user interface:
 ## Delete a protected branch
 
 From time to time, you may need to delete or clean up protected branches.
-User with [Maintainer permissions](../permissions.md) and greater can manually delete protected
+User with the [Maintainer role](../permissions.md) and greater can manually delete protected
 branches by using the GitLab web interface:
 
 1. Go to **Repository > Branches**.
diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md
index 260f355349d..17a9cd5c8c6 100644
--- a/doc/user/project/protected_tags.md
+++ b/doc/user/project/protected_tags.md
@@ -21,7 +21,7 @@ anyone without Maintainer [permissions](../permissions.md) is prevented from cre
 
 ## Configuring protected tags
 
-To protect a tag, you need to have at least Maintainer [permissions](../permissions.md).
+To protect a tag, you need to have at least the [Maintainer role](../permissions.md).
 
 1. Go to the project's **Settings > Repository**.
 
diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md
index 1ea21b1f269..7ef39ecbab3 100644
--- a/doc/user/project/releases/index.md
+++ b/doc/user/project/releases/index.md
@@ -209,7 +209,7 @@ deploy_to_production:
 
 To set a deploy freeze window in the UI, complete these steps:
 
-1. Sign in to GitLab as a user with project Maintainer [permissions](../../permissions.md).
+1. Sign in to GitLab as a user with the [Maintainer role](../../permissions.md).
 1. Navigate to **Project overview**.
 1. In the left navigation menu, navigate to **Settings > CI/CD**.
 1. Scroll to **Deploy freezes**.
diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md
index 6b79464005d..e9f214f08ce 100644
--- a/doc/user/project/repository/repository_mirroring.md
+++ b/doc/user/project/repository/repository_mirroring.md
@@ -22,14 +22,15 @@ There are two kinds of repository mirroring supported by GitLab:
 When the mirror repository is updated, all new branches, tags, and commits are visible in the
 project's activity feed.
 
-Users with [Maintainer access](../../permissions.md) to the project can also force an
+Users with the [Maintainer role](../../permissions.md) for the project can also force an
 immediate update, unless:
 
 - The mirror is already being updated.
 - The [limit for pull mirroring interval seconds](../../../administration/instance_limits.md#pull-mirroring-interval) has not elapsed since its last update.
 
-For security reasons, the URL to the original repository is only displayed to users with
-Maintainer or Owner permissions to the mirrored project.
+For security reasons, the URL to the original repository is only displayed to users with the
+[Maintainer role](../../permissions.md) or the [Owner role](../../permissions.md) for the mirrored
+project.
 
 ## Use cases
 
diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md
index f5fa6e37d1c..ebc77bb5b61 100644
--- a/doc/user/project/settings/import_export.md
+++ b/doc/user/project/settings/import_export.md
@@ -43,7 +43,7 @@ Note the following:
   and are moved to your configured `uploads_directory`. Every 24 hours, a specific worker deletes these export files.
 - Group members are exported as project members, as long as the user has
   maintainer or administrator access to the group where the exported project lives.
-- Project members with owner access are imported as maintainers.
+- Project members with the [Owner role](../../permissions.md) are imported as Maintainers.
 - Imported users can be mapped by their primary email on self-managed instances, if an administrative user (not an owner) does the import.
   Otherwise, a supplementary comment is left to mention that the original author and
   the MRs, notes, or issues are owned by the importer.
diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md
index 14bf924886e..ce8daa1d296 100644
--- a/doc/user/project/settings/index.md
+++ b/doc/user/project/settings/index.md
@@ -339,7 +339,7 @@ to transfer a project.
 
 You can transfer an existing project into a [group](../../group/index.md) if:
 
-- You have at least **Maintainer** [permissions](../../permissions.md#project-members-permissions) to that group.
+- You have at least the Maintainer** role in that group.
 - You're at least an **Owner** of the project to be transferred.
 - The group to which the project is being transferred to must allow creation of new projects.
 
@@ -362,7 +362,7 @@ namespace if needed.
 #### Delete a project
 
 NOTE:
-Only project owners and administrators have [permissions](../../permissions.md#project-members-permissions) to delete a project.
+Only project Owners and administrators have [permissions](../../permissions.md#project-members-permissions) to delete a project.
 
 To delete a project:
 
@@ -374,10 +374,10 @@ This action:
 
 - Deletes a project including all associated resources (issues, merge requests etc).
 - From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) on [Premium](https://about.gitlab.com/pricing/) or higher tiers,
-group owners can [configure](../../group/index.md#enable-delayed-project-removal) projects within a group
-to be deleted after a delayed period.
-When enabled, actual deletion happens after number of days
-specified in [instance settings](../../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay).
+  group Owners can [configure](../../group/index.md#enable-delayed-project-removal) projects within a group
+  to be deleted after a delayed period.
+  When enabled, actual deletion happens after number of days
+  specified in [instance settings](../../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay).
 
 WARNING:
 The default behavior of [Delayed Project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6 was changed to
@@ -410,7 +410,7 @@ To do so:
 1. Confirm the action by typing the project's path as instructed.
 
 NOTE:
-Only project owners have the [permissions](../../permissions.md#project-members-permissions)
+Only project Owners have the [permissions](../../permissions.md#project-members-permissions)
 to remove a fork relationship.
 
 ## Operations settings
diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md
index 51e306bf1fc..b7595f30dbc 100644
--- a/doc/user/project/wiki/index.md
+++ b/doc/user/project/wiki/index.md
@@ -123,7 +123,7 @@ For an example, read [Table of contents](../../markdown.md#table-of-contents).
 
 ## Delete a wiki page
 
-You need Maintainer [permissions](../../permissions.md) or higher to delete a wiki page:
+You need the [Maintainer role](../../permissions.md) or higher to delete a wiki page:
 
 1. Go to your project or group and select **Wiki**.
 1. Go to the page you want to delete.