Add latest changes from gitlab-org/gitlab@master

12 files changed, 259 insertions, 8 deletions

diff --git a/doc/administration/instance_limits.md b/doc/administration/instance_limits.md
index 24ffee088f3..682fba804a6 100644
--- a/doc/administration/instance_limits.md
+++ b/doc/administration/instance_limits.md
@@ -88,6 +88,20 @@ requests per user. For more information, read
 
 - **Default rate limit**: Disabled by default.
 
+### Files API
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68561) in GitLab 14.3.
+
+FLAG:
+On self-managed GitLab, by default this feature is not available. To make it available,
+ask an administrator to [enable the `files_api_throttling` flag](../administration/feature_flags.md). On GitLab.com, this feature is available but can be configured by GitLab.com administrators only.
+The feature is not ready for production use.
+
+This setting limits the request rate on the Packages API per user or IP address. For more information, read
+[Files API rate limits](../user/admin_area/settings/files_api_rate_limits.md).
+
+- **Default rate limit**: Disabled by default.
+
 ### Import/Export
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35728) in GitLab 13.2.
diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md
index e7edfb9f338..6d328739f3e 100644
--- a/doc/administration/repository_storage_paths.md
+++ b/doc/administration/repository_storage_paths.md
@@ -11,9 +11,10 @@ GitLab stores [repositories](../user/project/repository/index.md) on repository
 storage is either:
 
 - A `gitaly_address`, which points to a [Gitaly node](gitaly/index.md).
-- A `path`, which points directly to the directory where the repositories are stored. This method is
-  deprecated and [scheduled to be removed](https://gitlab.com/gitlab-org/gitaly/-/issues/1690) in
-  GitLab 14.0.
+- A `path`, which points directly to the directory where the repositories are stored. GitLab
+  directly accessing a directory containing repositories
+  [is deprecated](https://gitlab.com/gitlab-org/gitaly/-/issues/1690).
+  GitLab should be configured to access GitLab repositories though a `gitaly_address`.
 
 GitLab allows you to define multiple repository storages to distribute the storage load between
 several mount points. For example:
diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md
index abf9d7af229..fcb7477f226 100644
--- a/doc/api/oauth2.md
+++ b/doc/api/oauth2.md
@@ -412,6 +412,16 @@ prevent breaking changes introduced in [doorkeeper 5.0.2](https://github.com/doo
 
 Don't rely on these fields as they are slated for removal in a later release.
 
+## Revoke a token
+
+To revoke a token, use the `revoke` endpoint. The API returns a 200 response code and an empty
+JSON hash to indicate success. 
+
+```ruby
+parameters = 'client_id=APP_ID&client_secret=APP_SECRET&token=TOKEN'
+RestClient.post 'https://gitlab.example.com/oauth/revoke', parameters
+```
+
 ## OAuth 2.0 tokens and GitLab registries
 
 Standard OAuth 2.0 tokens support different degrees of access to GitLab
diff --git a/doc/api/project_relations_export.md b/doc/api/project_relations_export.md
new file mode 100644
index 00000000000..2016dcbd141
--- /dev/null
+++ b/doc/api/project_relations_export.md
@@ -0,0 +1,111 @@
+---
+stage: Manage
+group: Import
+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
+---
+
+# Project Relations Export API **(FREE)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/70330) in GitLab 14.4 behind the `bulk_import` [feature flag](../administration/feature_flags.md), disabled by default.
+
+FLAG:
+On GitLab.com, this feature is available.
+On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to
+[disable the `bulk_import` flag](../administration/feature_flags.md).
+The feature is not ready for production use. It is still in experimental stage and might change in the future.
+
+With the Project Relations Export API, you can partially export project structure. This API is
+similar to [project export](project_import_export.md),
+but it exports each top-level relation (for example, milestones/boards/labels) as a separate file
+instead of one archive. The project relations export API is primarily used in
+[group migration](../user/group/import/index.md#enable-or-disable-gitlab-group-migration)
+to support group project import.
+
+## Schedule new export
+
+Start a new project relations export:
+
+```plaintext
+POST /projects/:id/export_relations
+```
+
+| Attribute | Type           | Required | Description                              |
+| --------- | -------------- | -------- | ---------------------------------------- |
+| `id`      | integer/string | yes      | ID of the project owned by the authenticated user. |
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/export_relations"
+```
+
+```json
+{
+  "message": "202 Accepted"
+}
+```
+
+## Export status
+
+View the status of the relations export:
+
+```plaintext
+GET /projects/:id/export_relations/status
+```
+
+| Attribute | Type           | Required | Description                              |
+| --------- | -------------- | -------- | ---------------------------------------- |
+| `id`      | integer/string | yes      | ID of the project owned by the authenticated user. |
+
+```shell
+curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" \
+     "https://gitlab.example.com/api/v4/projects/1/export_relations/status"
+```
+
+The status can be one of the following:
+
+- `0`: `started`
+- `1`: `finished`
+- `-1`: `failed`
+
+- `0` - `started`
+- `1` - `finished`
+- `-1` - `failed`
+
+```json
+[
+  {
+    "relation": "project_badges",
+    "status": 1,
+    "error": null,
+    "updated_at": "2021-05-04T11:25:20.423Z"
+  },
+  {
+    "relation": "boards",
+    "status": 1,
+    "error": null,
+    "updated_at": "2021-05-04T11:25:20.085Z"
+  }
+]
+```
+
+## Export download
+
+Download the finished relations export:
+
+```plaintext
+GET /projects/:id/export_relations/download
+```
+
+| Attribute       | Type           | Required | Description                              |
+| --------------- | -------------- | -------- | ---------------------------------------- |
+| `id`            | integer/string | yes      | ID of the project owned by the authenticated user. |
+| `relation`      | string         | yes      | Name of the project top-level relation to download. |
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name \
+     --remote-name "https://gitlab.example.com/api/v4/projects/1/export_relations/download?relation=labels"
+```
+
+```shell
+ls labels.ndjson.gz
+labels.ndjson.gz
+```
diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md
index 1e33aadbc1b..4fb1a94e294 100644
--- a/doc/api/repository_files.md
+++ b/doc/api/repository_files.md
@@ -7,9 +7,11 @@ type: reference, api
 
 # Repository files API **(FREE)**
 
-**CRUD for repository files**
+You can fetch, create, update, and delete files in your repository with this API.
+You can also [configure rate limits](../user/admin_area/settings/files_api_rate_limits.md)
+for this API.
 
-**Create, read, update, and delete repository files using this API**
+## Available scopes for personal access tokens
 
 The different scopes available using [personal access tokens](../user/profile/personal_access_tokens.md) are depicted
 in the following table.
@@ -19,8 +21,6 @@ in the following table.
 | `read_repository` | Allows read-access to the repository files. |
 | `api` | Allows read-write access to the repository files. |
 
-> `read_repository` scope was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23534) in GitLab 11.6.
-
 ## Get file from repository
 
 Allows you to receive information about file in repository like name, size,
diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md
index eafe0e7a1c2..2c6aab1a3aa 100644
--- a/doc/development/documentation/styleguide/word_list.md
+++ b/doc/development/documentation/styleguide/word_list.md
@@ -471,6 +471,15 @@ Do not use **roles** and **permissions** interchangeably. Each user is assigned
 
 Use lowercase for **runners**. These are the agents that run CI/CD jobs. See also [GitLab Runner](#gitlab-runner) and [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529).
 
+## (s)
+
+Do not use **(s)** to make a word optionally plural. It can slow down comprehension. For example:
+
+Do: Select the jobs you want.
+Do not: Select the job(s) you want.
+
+If you can select multiples of something, then write the word as plural.
+
 ## sanity check
 
 Do not use **sanity check**. Use **check for completeness** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml))
diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md
index 5df6c4f28b7..12ce2314206 100644
--- a/doc/integration/oauth_provider.md
+++ b/doc/integration/oauth_provider.md
@@ -88,6 +88,25 @@ To create an application for your GitLab instance:
 When creating application in the **Admin Area** , you can mark it as _trusted_.
 The user authorization step is automatically skipped for this application.
 
+## Expiring Access Tokens
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21745) in GitLab 14.3.
+
+By default, all new applications expire access tokens after 2 hours. In GitLab 14.2 and
+earlier, OAuth access tokens had no expiration.
+
+All integrations should update to support access token refresh.
+
+When creating new applications, you can opt-out of expiry for backward compatibility by clearing
+**Expire access tokens** when creating them. The ability to opt-out
+[is deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/340848).
+
+Existing:
+
+- Applications can have expiring access tokens. Edit the application and select
+  **Expire access tokens** to enable them. 
+- Tokens must be [revoked](../api/oauth2.md#revoke-a-token) or they don't expire.
+
 ## Authorized applications
 
 Every application you authorize with your GitLab credentials is shown
diff --git a/doc/security/rate_limits.md b/doc/security/rate_limits.md
index 6045dece0c2..a5249cb162f 100644
--- a/doc/security/rate_limits.md
+++ b/doc/security/rate_limits.md
@@ -35,6 +35,7 @@ These are rate limits you can set in the Admin Area of your instance:
 - [User and IP rate limits](../user/admin_area/settings/user_and_ip_rate_limits.md)
 - [Package registry rate limits](../user/admin_area/settings/package_registry_rate_limits.md)
 - [Git LFS rate limits](../user/admin_area/settings/git_lfs_rate_limits.md)
+- [Files API rate limits](../user/admin_area/settings/files_api_rate_limits.md)
 
 ## Non-configurable limits
 
diff --git a/doc/user/admin_area/settings/files_api_rate_limits.md b/doc/user/admin_area/settings/files_api_rate_limits.md
new file mode 100644
index 00000000000..f91d4b2fb0c
--- /dev/null
+++ b/doc/user/admin_area/settings/files_api_rate_limits.md
@@ -0,0 +1,56 @@
+---
+stage: Create
+group: Source Code
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+type: reference
+---
+
+# Files API rate limits **(FREE SELF)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68561) in GitLab 14.3.
+
+FLAG:
+On self-managed GitLab, by default this feature is not available. To make it
+available, ask an administrator to [enable the `files_api_throttling` flag](../../../administration/feature_flags.md).
+On GitLab.com, this feature is available but can be configured by GitLab.com
+administrators only. The feature is not ready for production use.
+
+The [Repository files API](../../../api/repository_files.md) enables you to
+fetch, create, update, and delete files in your repository. To improve the security
+and durability of your web application, you can enforce
+[rate limits](../../../security/rate_limits.md) on this API. Any rate limits you
+create for the Files API override the [general user and IP rate limits](user_and_ip_rate_limits.md).
+
+## Define Files API rate limits
+
+Rate limits for the Files API are disabled by default. When enabled, they supersede
+the general user and IP rate limits for requests to the
+[Repository files API](../../../api/repository_files.md). You can keep any general user
+and IP rate limits already in place, and increase or decrease the rate limits
+for the Files API. No other new features are provided by this override.
+
+Prerequisites:
+
+- You must have the Administrator role for your instance.
+- The `files_api_throttling` feature flag must be enabled.
+
+To override the general user and IP rate limits for requests to the Repository files API:
+
+1. On the top bar, select **Menu > Admin**.
+1. On the left sidebar, select **Settings > Network**.
+1. Expand **Files API Rate Limits**.
+1. Select the check boxes for the types of rate limits you want to enable:
+   - **Unauthenticated API request rate limit**
+   - **Authenticated API request rate limit**
+1. _If you enabled unauthenticated API request rate limits:_
+   1. Select the **Max unauthenticated API requests per period per IP**.
+   1. Select the **Unauthenticated API rate limit period in seconds**.
+1. _If you enabled authenticated API request rate limits:_
+   1. Select the **Max authenticated API requests per period per user**.
+   1. Select the **Authenticated API rate limit period in seconds**.
+
+## Resources
+
+- [Rate limits](../../../security/rate_limits.md)
+- [Repository files API](../../../api/repository_files.md)
+- [User and IP rate limits](user_and_ip_rate_limits.md)
diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md
index ec5f3ca812f..f0bd378413a 100644
--- a/doc/user/admin_area/settings/index.md
+++ b/doc/user/admin_area/settings/index.md
@@ -98,6 +98,7 @@ To access the default page for Admin Area settings:
 | [User and IP rate limits](user_and_ip_rate_limits.md) | Configure limits for web and API requests. |
 | [Package Registry Rate Limits](package_registry_rate_limits.md) | Configure specific limits for Packages API requests that supersede the user and IP rate limits. |
 | [Git LFS Rate Limits](git_lfs_rate_limits.md) | Configure specific limits for Git LFS requests that supersede the user and IP rate limits. |
+| [Files API Rate Limits](files_api_rate_limits.md) | Configure specific limits for Files API requests that supersede the user and IP rate limits. |
 | [Outbound requests](../../../security/webhooks.md) | Allow requests to the local network from hooks and services. |
 | [Protected Paths](protected_paths.md) | Configure paths to be protected by Rack Attack. |
 | [Incident Management](../../../operations/incident_management/index.md) Limits | Limit the number of inbound alerts that can be sent to a project. |
diff --git a/doc/user/admin_area/settings/user_and_ip_rate_limits.md b/doc/user/admin_area/settings/user_and_ip_rate_limits.md
index 32f08801c76..c138096768e 100644
--- a/doc/user/admin_area/settings/user_and_ip_rate_limits.md
+++ b/doc/user/admin_area/settings/user_and_ip_rate_limits.md
@@ -189,6 +189,8 @@ The possible names are:
 - `throttle_unauthenticated_packages_api`
 - `throttle_authenticated_packages_api`
 - `throttle_authenticated_git_lfs`
+- `throttle_unauthenticated_files_api`
+- `throttle_authenticated_files_api`
 
 For example, to try out throttles for all authenticated requests to
 non-protected paths can be done by setting
diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md
index bd143d8608a..4d71919299c 100644
--- a/doc/user/application_security/policies/index.md
+++ b/doc/user/application_security/policies/index.md
@@ -255,6 +255,10 @@ The policy editor currently only supports the YAML mode. The Rule mode is tracke
 
 The YAML file with Scan Execution Policies consists of an array of objects matching Scan Execution Policy Schema nested under the `scan_execution_policy` key. You can configure a maximum of 5 policies under the `scan_execution_policy` key.
 
+When you save a new policy, GitLab validates its contents against [this JSON schema](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/validators/json_schemas/security_orchestration_policy.json).
+If you're not familiar with how to read [JSON schemas](https://json-schema.org/),
+the following sections and tables provide an alternative.
+
 | Field | Type | Possible values | Description |
 |-------|------|-----------------|-------------|
 | `scan_execution_policy` | `array` of Scan Execution Policy |  | List of scan execution policies (maximum 5) |
@@ -291,6 +295,8 @@ This rule enforces the defined actions and schedules a scan on the provided date
 
 #### `cluster` schema
 
+Use this schema to define `clusters` objects in the [`schedule` rule type](#schedule-rule-type).
+
 | Field        | Type                | Possible values          | Description |
 |--------------|---------------------|--------------------------|-------------|
 | `containers` | `array` of `string` | | The container name that will be scanned (only the first value is currently supported). |
@@ -329,7 +335,10 @@ Note the following:
   They will use predefined CI/CD variables defined for your project. Cluster selection with the `clusters` object is supported for the `schedule` rule type.
   Cluster with name provided in `clusters` object must be created and configured for the project. To be able to successfully perform the `container_scanning`/`cluster_image_scanning` scans for the cluster you must follow instructions for the [Cluster Image Scanning feature](../cluster_image_scanning/index.md#prerequisites).
 
-Here's an example:
+### Example security policies project
+
+You can use this example in a `.gitlab/security-policies/policy.yml`, as described in
+[Security policies project](#security-policies-project).
 
 ```yaml
 ---
@@ -398,6 +407,24 @@ In this example:
 - Cluster Image Scanning scan runs every 24h. The scan runs on the `production-cluster` cluster and fetches vulnerabilities
   from the container with the name `database` configured for deployment with the name `production-application` in the `production-namespace` namespace.
 
+### Example for scan execution policy editor
+
+You can use this example in the YAML mode of the [Scan Execution Policy editor](#scan-execution-policy-editor).
+It corresponds to a single object from the previous example.
+
+```yaml
+name: Enforce Secret Detection and Container Scanning in every default branch pipeline
+description: This policy enforces pipeline configuration to have a job with Secret Detection and Container Scanning scans for the default branch
+enabled: true
+rules:
+  - type: pipeline
+    branches:
+      - main
+actions:
+  - scan: secret_detection
+  - scan: container_scanning
+```
+
 ## Roadmap
 
 See the [Category Direction page](https://about.gitlab.com/direction/protect/container_network_security/)