Merge branch 'docs-project-level-access-tokens-project-bots' into 'master'

Docs: Project access tokens (PrAT)

See merge request gitlab-org/gitlab!30562

doc/api/README.md

@@ -77,10 +77,11 @@ authentication is not provided. For
 those cases where it is not required, this will be mentioned in the documentation
 for each individual endpoint. For example, the [`/projects/:id` endpoint](projects.md).
 
-There are four ways to authenticate with the GitLab API:
+There are several ways to authenticate with the GitLab API:
 
 1. [OAuth2 tokens](#oauth2-tokens)
-1. [Personal access tokens](#personal-access-tokens)
+1. [Personal access tokens](../user/profile/personal_access_tokens.md)
+1. [Project access tokens](../user/project/settings/project_access_tokens.md) **(CORE ONLY)**
 1. [Session cookie](#session-cookie)
 1. [GitLab CI/CD job token](#gitlab-ci-job-token) **(Specific endpoints only)**
 
@@ -117,31 +118,29 @@ curl --header "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api
 
 Read more about [GitLab as an OAuth2 provider](oauth2.md).
 
-### Personal access tokens
+### Personal/project access tokens
 
-You can use a [personal access token](../user/profile/personal_access_tokens.md) to authenticate with the API by passing it in either the
-`private_token` parameter or the `Private-Token` header.
+Access tokens can be used to authenticate with the API by passing it in either the `private_token` parameter
+or the `Private-Token` header.
 
-Example of using the personal access token in a parameter:
+Example of using the personal/project access token in a parameter:
 
 ```shell
 curl https://gitlab.example.com/api/v4/projects?private_token=<your_access_token>
 ```
 
-Example of using the personal access token in a header:
+Example of using the personal/project access token in a header:
 
 ```shell
 curl --header "Private-Token: <your_access_token>" https://gitlab.example.com/api/v4/projects
 ```
 
-You can also use personal access tokens with OAuth-compliant headers:
+You can also use personal/project access tokens with OAuth-compliant headers:
 
 ```shell
 curl --header "Authorization: Bearer <your_access_token>" https://gitlab.example.com/api/v4/projects
 ```
 
-Read more about [personal access tokens](../user/profile/personal_access_tokens.md).
-
 ### Session cookie
 
 When signing in to the main GitLab application, a `_gitlab_session` cookie is

doc/topics/authentication/index.md

@@ -38,7 +38,8 @@ This page gathers all the resources for the topic **Authentication** within GitL
 ## API
 
 - [OAuth 2 Tokens](../../api/README.md#oauth2-tokens)
-- [Personal access tokens](../../api/README.md#personal-access-tokens)
+- [Personal access tokens](../../api/README.md#personalproject-access-tokens)
+- [Project access tokens](../../api/README.md#personalproject-access-tokens) **(CORE ONLY)**
 - [Impersonation tokens](../../api/README.md#impersonation-tokens)
 - [GitLab as an OAuth2 provider](../../api/oauth2.md#gitlab-as-an-oauth2-provider)
 

doc/user/permissions.md

@@ -148,6 +148,7 @@ The following table depicts the various user permission levels in a project.
 | Delete wiki pages                                 |         |            |             | ✓        | ✓      |
 | View project Audit Events                         |         |            |             | ✓        | ✓      |
 | Manage [push rules](../push_rules/push_rules.md)  |         |            |             | ✓        | ✓      |
+| Manage [project access tokens](./project/settings/project_access_tokens.md) **(CORE ONLY)** |         |            |             | ✓        | ✓      |
 | Switch visibility level                           |         |            |             |          | ✓      |
 | Transfer project to another namespace             |         |            |             |          | ✓      |
 | Remove fork relationship                          |         |            |             |          | ✓      |

doc/user/profile/personal_access_tokens.md

@@ -8,7 +8,7 @@ type: concepts, howto
 > - [Notifications about expiring tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) added in GitLab 12.6.
 > - [Token lifetime limits](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) added in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6.
 
-If you're unable to use [OAuth2](../../api/oauth2.md), you can use a personal access token to authenticate with the [GitLab API](../../api/README.md#personal-access-tokens).
+If you're unable to use [OAuth2](../../api/oauth2.md), you can use a personal access token to authenticate with the [GitLab API](../../api/README.md#personalproject-access-tokens).
 
 You can also use personal access tokens with Git to authenticate over HTTP or SSH. Personal access tokens are required when [Two-Factor Authentication (2FA)](../account/two_factor_authentication.md) is enabled. In both cases, you can authenticate with a token in place of your password.
 
@@ -17,7 +17,7 @@ Personal access tokens expire on the date you define, at midnight UTC.
 - GitLab runs a check at 01:00 AM UTC every day to identify personal access tokens that will expire in under seven days. The owners of these tokens are notified by email.
 - In GitLab Ultimate, administrators may [limit the lifetime of personal access tokens](../admin_area/settings/account_and_limit_settings.md#limiting-lifetime-of-personal-access-tokens-ultimate-only).
 
-For examples of how you can use a personal access token to authenticate with the API, see the following section from our [API Docs](../../api/README.md#personal-access-tokens).
+For examples of how you can use a personal access token to authenticate with the API, see the following section from our [API Docs](../../api/README.md#personalproject-access-tokens).
 
 GitLab also offers [impersonation tokens](../../api/README.md#impersonation-tokens) which are created by administrators via the API. They're a great fit for automated authentication as a specific user.
 

doc/user/project/settings/project_access_tokens.md

+# Project access tokens **(CORE ONLY)**
+
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2587) in GitLab 13.0.
+
+Project access tokens are scoped to a project and can be used to authenticate with the [GitLab API](../../../api/README.md#personalproject-access-tokens).
+
+You can also use project access tokens with Git to authenticate over HTTP or SSH.
+
+Project access tokens expire on the date you define, at midnight UTC.
+
+For examples of how you can use a project access token to authenticate with the API, see the following section from our [API Docs](../../../api/README.md#personalproject-access-tokens).
+
+## Creating a project access token
+
+1. Log in to GitLab.
+1. Navigate to the project you would like to create an access token for.
+1. In the **{settings}** **Settings** menu choose **Access Tokens**.
+1. Choose a name and optional expiry date for the token.
+1. Choose the [desired scopes](#limiting-scopes-of-a-project-access-token).
+1. Click the **Create project access token** button.
+1. Save the project access token somewhere safe. Once you leave or refresh
+   the page, you won't be able to access it again.
+
+## Project bot users
+
+For each project access token created, a bot user will also be created and added to the project with
+["Maintainer" level permissions](../../permissions.md#project-members-permissions). API calls made with a
+project access token will be associated to the corresponding bot user.
+
+These users will appear in **{settings}** **Settings > Members** but can not be modified.
+Furthermore, the bot user can not be added to any other project.
+
+When the project access token is [revoked](#revoking-a-project-access-token) the bot user will be deleted and all
+records will be moved to a system-wide user with the username "Ghost User". For more information,
+see [Associated Records](../../profile/account/delete_account.md#associated-records).
+
+## Revoking a project access token
+
+At any time, you can revoke any project access token by clicking the
+respective **Revoke** button in **{settings}** **Settings > Access Tokens**.
+
+## Limiting scopes of a project access token
+
+Project access tokens can be created with one or more scopes that allow various
+actions that a given token can perform. The available scopes are depicted in
+the following table.
+
+| Scope              |  Description |
+| ------------------ |  ----------- |
+| `api`              | Grants complete read/write access to scoped project API. |
+| `read_api`         | Grants read access to the scoped project API. |
+| `read_registry`    | Allows read-access (pull) to [container registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. |
+| `write_registry`   | Allows write-access (push) to [container registry](../../packages/container_registry/index.md). |
+| `read_repository`  | Allows read-only access (pull) to the repository. |
+| `write_repository` | Allows read-write access (pull, push) to the repository. |