Merge branch 'eread/clarify-permissions-and-roles' into 'master'

Clarify permissions and roles, and add rule

See merge request gitlab-org/gitlab!62652

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

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

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.

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.

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
 

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
 

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
 

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 |

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:
 

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.
 

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
 

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
 

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.

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

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.
 

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:
 

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:
 

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.
 

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)

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).

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"

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:
 

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.

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)

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.

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

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.

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.
 

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)

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 |
 |--------------------------------------------------------|-------|----------|-----------|------------|-------|

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)**

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,

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.

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
 

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

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)

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
 

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.
 

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

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**.

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**.
 

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**.

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
 

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.

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

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.