Move permissions/permissions.md to user/permissions.md

1 files changed, 131 insertions, 0 deletions

diff --git a/doc/user/permissions.md b/doc/user/permissions.md
new file mode 100644
index 00000000000..8fc10a13f91
--- /dev/null
+++ b/doc/user/permissions.md
@@ -0,0 +1,131 @@
+# Permissions
+
+Users have different abilities depending on the access level they have in a
+particular group or project. If a user is both in a group's project and the
+project itself, the highest permission level is used.
+
+On public and internal projects the Guest role is not enforced. All users will
+be able to create issues, leave comments, and pull or download the project code.
+
+GitLab administrators receive all permissions.
+
+To add or import a user, you can follow the [project users and members
+documentation](../workflow/add-user/add-user.md).
+
+## Project
+
+The following table depicts the various user permission levels in a project.
+
+| Action                                | Guest   | Reporter   | Developer   | Master   | Owner  |
+|---------------------------------------|---------|------------|-------------|----------|--------|
+| Create new issue                      | ✓       | ✓          | ✓           | ✓        | ✓      |
+| Leave comments                        | ✓       | ✓          | ✓           | ✓        | ✓      |
+| See a list of builds                  | ✓ [^1]  | ✓          | ✓           | ✓        | ✓      |
+| See a build log                       | ✓ [^1]  | ✓          | ✓           | ✓        | ✓      |
+| Download and browse build artifacts   | ✓ [^1]  | ✓          | ✓           | ✓        | ✓      |
+| Pull project code                     |         | ✓          | ✓           | ✓        | ✓      |
+| Download project                      |         | ✓          | ✓           | ✓        | ✓      |
+| Create code snippets                  |         | ✓          | ✓           | ✓        | ✓      |
+| Manage issue tracker                  |         | ✓          | ✓           | ✓        | ✓      |
+| Manage labels                         |         | ✓          | ✓           | ✓        | ✓      |
+| See a commit status                   |         | ✓          | ✓           | ✓        | ✓      |
+| See a container registry              |         | ✓          | ✓           | ✓        | ✓      |
+| See environments                      |         | ✓          | ✓           | ✓        | ✓      |
+| Manage merge requests                 |         |            | ✓           | ✓        | ✓      |
+| Create new merge request              |         |            | ✓           | ✓        | ✓      |
+| Create new branches                   |         |            | ✓           | ✓        | ✓      |
+| Push to non-protected branches        |         |            | ✓           | ✓        | ✓      |
+| Force push to non-protected branches  |         |            | ✓           | ✓        | ✓      |
+| Remove non-protected branches         |         |            | ✓           | ✓        | ✓      |
+| Add tags                              |         |            | ✓           | ✓        | ✓      |
+| Write a wiki                          |         |            | ✓           | ✓        | ✓      |
+| Cancel and retry builds               |         |            | ✓           | ✓        | ✓      |
+| Create or update commit status        |         |            | ✓           | ✓        | ✓      |
+| Update a container registry           |         |            | ✓           | ✓        | ✓      |
+| Remove a container registry image     |         |            | ✓           | ✓        | ✓      |
+| Create new environments               |         |            | ✓           | ✓        | ✓      |
+| Create new milestones                 |         |            |             | ✓        | ✓      |
+| Add new team members                  |         |            |             | ✓        | ✓      |
+| Push to protected branches            |         |            |             | ✓        | ✓      |
+| Enable/disable branch protection      |         |            |             | ✓        | ✓      |
+| Turn on/off protected branch push for devs|         |            |             | ✓        | ✓      |
+| Rewrite/remove Git tags               |         |            |             | ✓        | ✓      |
+| Edit project                          |         |            |             | ✓        | ✓      |
+| Add deploy keys to project            |         |            |             | ✓        | ✓      |
+| Configure project hooks               |         |            |             | ✓        | ✓      |
+| Manage runners                        |         |            |             | ✓        | ✓      |
+| Manage build triggers                 |         |            |             | ✓        | ✓      |
+| Manage variables                      |         |            |             | ✓        | ✓      |
+| Delete environments                   |         |            |             | ✓        | ✓      |
+| Switch visibility level               |         |            |             |          | ✓      |
+| Transfer project to another namespace |         |            |             |          | ✓      |
+| Remove project                        |         |            |             |          | ✓      |
+| Force push to protected branches [^2] |         |            |             |          |        |
+| Remove protected branches [^2]        |         |            |             |          |        |
+
+[^1]: If **Allow guest to access builds** is enabled in CI settings
+[^2]: Not allowed for Guest, Reporter, Developer, Master, or Owner
+
+## Group
+
+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.
+
+| Action                  | Guest | Reporter | Developer | Master | Owner |
+|-------------------------|-------|----------|-----------|--------|-------|
+| Browse group            | ✓     | ✓        | ✓         | ✓      | ✓     |
+| Edit group              |       |          |           |        | ✓     |
+| Create project in group |       |          |           | ✓      | ✓     |
+| Manage group members    |       |          |           |        | ✓     |
+| Remove group            |       |          |           |        | ✓     |
+
+## External Users
+
+In cases where it is desired that a user has access only to some internal or
+private projects, there is the option of creating **External Users**. This
+feature may be useful when for example a contractor is working on a given
+project and should only have access to that project.
+
+External users can only access projects to which they are explicitly granted
+access, thus hiding all other internal or private ones from them. Access can be
+granted by adding the user as member to the project or group.
+
+They will, like usual users, receive a role in the project or group with all
+the abilities that are mentioned in the table above. They cannot however create
+groups or projects, and they have the same access as logged out users in all
+other cases.
+
+An administrator can flag a user as external [through the API](../api/users.md)
+or by checking the checkbox on the admin panel. As an administrator, navigate
+to **Admin > Users** to create a new user or edit an existing one. There, you
+will find the option to flag the user as external.
+
+By default new users are not set as external users. This behavior can be changed
+by an administrator under **Admin > Application Settings**.
+
+## GitLab CI
+
+GitLab CI permissions rely on the role the user has in GitLab. There are four
+permission levels it total:
+
+- admin
+- master
+- developer
+- guest/reporter
+
+The admin user can perform any action on GitLab CI in scope of the GitLab
+instance and project. In addition, all admins can use the admin interface under
+`/admin/runners`.
+
+| Action                                | Guest, Reporter | Developer   | Master   | Admin  |
+|---------------------------------------|-----------------|-------------|----------|--------|
+| See commits and builds                | ✓               | ✓           | ✓        | ✓      |
+| Retry or cancel build                 |                 | ✓           | ✓        | ✓      |
+| Remove project                        |                 |             | ✓        | ✓      |
+| Create project                        |                 |             | ✓        | ✓      |
+| Change project configuration          |                 |             | ✓        | ✓      |
+| Add specific runners                  |                 |             | ✓        | ✓      |
+| Add shared runners                    |                 |             |          | ✓      |
+| See events in the system              |                 |             |          | ✓      |
+| Admin interface                       |                 |             |          | ✓      |