Add latest changes from gitlab-org/gitlab@master

11 files changed, 470 insertions, 473 deletions

diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md
index 5ec1fa6c040..7bf9fb0827a 100644
--- a/doc/api/deploy_keys.md
+++ b/doc/api/deploy_keys.md
@@ -43,6 +43,7 @@ Example response:
     "fingerprint": "4a:9d:64:15:ed:3a:e6:07:6e:89:36:b3:3b:03:05:d9",
     "fingerprint_sha256": "SHA256:Jrs3LD1Ji30xNLtTVf9NDCj7kkBgPBb2pjvTZ3HfIgU",
     "created_at": "2013-10-02T10:12:29Z",
+    "expires_at": null,
     "projects_with_write_access": [
       {
         "id": 73,
@@ -71,6 +72,7 @@ Example response:
     "fingerprint": "0b:cf:58:40:b9:23:96:c7:ba:44:df:0e:9e:87:5e:75",
     "fingerprint_sha256": "SHA256:lGI/Ys/Wx7PfMhUO1iuBH92JQKYN+3mhJZvWO4Q5ims",
     "created_at": "2013-10-02T11:12:29Z",
+    "expires_at": null,
     "projects_with_write_access": []
   }
 ]
@@ -103,6 +105,7 @@ Example response:
     "fingerprint": "4a:9d:64:15:ed:3a:e6:07:6e:89:36:b3:3b:03:05:d9",
     "fingerprint_sha256": "SHA256:Jrs3LD1Ji30xNLtTVf9NDCj7kkBgPBb2pjvTZ3HfIgU",
     "created_at": "2013-10-02T10:12:29Z",
+    "expires_at": null,
     "can_push": false
   },
   {
@@ -112,6 +115,7 @@ Example response:
     "fingerprint": "0b:cf:58:40:b9:23:96:c7:ba:44:df:0e:9e:87:5e:75",
     "fingerprint_sha256": "SHA256:lGI/Ys/Wx7PfMhUO1iuBH92JQKYN+3mhJZvWO4Q5ims",
     "created_at": "2013-10-02T11:12:29Z",
+    "expires_at": null,
     "can_push": false
   }
 ]
@@ -205,6 +209,7 @@ Example response:
   "fingerprint": "4a:9d:64:15:ed:3a:e6:07:6e:89:36:b3:3b:03:05:d9",
   "fingerprint_sha256": "SHA256:Jrs3LD1Ji30xNLtTVf9NDCj7kkBgPBb2pjvTZ3HfIgU",
   "created_at": "2013-10-02T10:12:29Z",
+  "expires_at": null,
   "can_push": false
 }
 ```
@@ -220,12 +225,13 @@ project only if the original one is accessible by the same user.
 POST /projects/:id/deploy_keys
 ```
 
-| Attribute  | Type | Required | Description |
-| ---------  | ---- | -------- | ----------- |
-| `id`       | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user |
-| `title`    | string  | yes | New deploy key's title |
-| `key`      | string  | yes | New deploy key |
-| `can_push` | boolean | no  | Can deploy key push to the project's repository |
+| Attribute    | Type | Required | Description |
+| -----------  | ---- | -------- | ----------- |
+| `id`         | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user |
+| `title`      | string   | yes | New deploy key's title |
+| `key`        | string   | yes | New deploy key |
+| `expires_at` | datetime | no | Expiration date for the deploy key. Does not expire if no value is provided. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
+| `can_push`   | boolean  | no  | Can deploy key push to the project's repository |
 
 ```shell
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \
@@ -241,7 +247,8 @@ Example response:
    "id" : 12,
    "title" : "My deploy key",
    "can_push": true,
-   "created_at" : "2015-08-29T12:44:31.550Z"
+   "created_at" : "2015-08-29T12:44:31.550Z",
+   "expires_at": null
 }
 ```
 
@@ -272,6 +279,7 @@ Example response:
    "title": "New deploy key",
    "key": "ssh-rsa AAAA...",
    "created_at": "2015-08-29T12:44:31.550Z",
+   "expires_at": null,
    "can_push": true
 }
 ```
@@ -317,7 +325,8 @@ Example response:
    "key" : "ssh-rsa AAAA...",
    "id" : 12,
    "title" : "My deploy key",
-   "created_at" : "2015-08-29T12:44:31.550Z"
+   "created_at" : "2015-08-29T12:44:31.550Z",
+   "expires_at": null
 }
 ```
 
diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md
index 61b7f623660..b85405823e6 100644
--- a/doc/api/graphql/reference/index.md
+++ b/doc/api/graphql/reference/index.md
@@ -22998,6 +22998,7 @@ Available fields to be exported as CSV.
 | <a id="availableexportfieldsauthor"></a>`AUTHOR` | Author name. |
 | <a id="availableexportfieldsauthor_username"></a>`AUTHOR_USERNAME` | Author username. |
 | <a id="availableexportfieldscreated_at"></a>`CREATED_AT` | Date of creation. |
+| <a id="availableexportfieldsdescription"></a>`DESCRIPTION` | Description. |
 | <a id="availableexportfieldsid"></a>`ID` | Unique identifier. |
 | <a id="availableexportfieldstitle"></a>`TITLE` | Title. |
 | <a id="availableexportfieldstype"></a>`TYPE` | Type of the work item. |
diff --git a/doc/ci/cloud_services/index.md b/doc/ci/cloud_services/index.md
index 115488c3f73..d2d609196e4 100644
--- a/doc/ci/cloud_services/index.md
+++ b/doc/ci/cloud_services/index.md
@@ -54,61 +54,7 @@ as a starting point, and for more information about supply chain attacks, see
 
 ## How it works
 
-Each job can be configured with ID tokens, which are provided as a CI/CD variable. These JWTs can be used to authenticate with the OIDC-supported cloud provider such as AWS, Azure, GCP, or Vault.
-
-The following fields are included in the JWT:
-
-| Field                   | When   | Description |
-| ----------------------- | ------ | ----------- |
-| `aud`                   | Always | Specified in the [ID tokens](../yaml/index.md#id_tokens) configuration |
-| `jti`                   | Always | Unique identifier for this token |
-| `iss`                   | Always | Issuer, the domain of your GitLab instance |
-| `iat`                   | Always | Issued at |
-| `nbf`                   | Always | Not valid before |
-| `exp`                   | Always | Expires at |
-| `sub`                   | Always |`project_path:{group}/{project}:ref_type:{type}:ref:{branch_name}` |
-| `namespace_id`          | Always | Use this to scope to group or user level namespace by ID |
-| `namespace_path`        | Always | Use this to scope to group or user level namespace by path |
-| `project_id`            | Always | Use this to scope to project by ID |
-| `project_path`          | Always | Use this to scope to project by path |
-| `user_id`               | Always | ID of the user executing the job |
-| `user_login`            | Always | Username of the user executing the job |
-| `user_email`            | Always | Email of the user executing the job |
-| `pipeline_id`           | Always | ID of this pipeline |
-| `pipeline_source`       | Always | [Pipeline source](../jobs/job_control.md#common-if-clauses-for-rules) |
-| `job_id`                | Always | ID of this job |
-| `ref`                   | Always | Git ref for this job |
-| `ref_type`              | Always | Git ref type, either `branch` or `tag` |
-| `ref_protected`         | Always | `true` if this Git ref is protected, `false` otherwise |
-| `environment`           | Job is creating a deployment | Environment this job deploys to ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294440) in GitLab 13.9) |
-| `environment_protected` | Job is creating a deployment |`true` if deployed environment is protected, `false` otherwise ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294440) in GitLab 13.9) |
-
-```json
-{
-  "jti": "c82eeb0c-5c6f-4a33-abf5-4c474b92b558",
-  "iss": "https://gitlab.example.com",
-  "aud": "https://vault.example.com",
-  "iat": 1585710286,
-  "nbf": 1585798372,
-  "exp": 1585713886,
-  "sub": "project_path:mygroup/myproject:ref_type:branch:ref:main",
-  "namespace_id": "1",
-  "namespace_path": "mygroup",
-  "project_id": "22",
-  "project_path": "mygroup/myproject",
-  "user_id": "42",
-  "user_login": "myuser",
-  "user_email": "myuser@example.com",
-  "pipeline_id": "1212",
-  "pipeline_source": "web",
-  "job_id": "1212",
-  "ref": "auto-deploy-2020-04-01",
-  "ref_type": "branch",
-  "ref_protected": "true",
-  "environment": "production",
-  "environment_protected": "true"
-}
-```
+Each job can be configured with ID tokens, which are provided as a CI/CD variable containing the [token payload](../secrets/id_token_authentication.md#token-payload). These JWTs can be used to authenticate with the OIDC-supported cloud provider such as AWS, Azure, GCP, or Vault.
 
 ### Authorization workflow
 
diff --git a/doc/ci/secrets/id_token_authentication.md b/doc/ci/secrets/id_token_authentication.md
index b10763b40d6..d6d1f62e47d 100644
--- a/doc/ci/secrets/id_token_authentication.md
+++ b/doc/ci/secrets/id_token_authentication.md
@@ -35,60 +35,64 @@ services with which a token can authenticate. This reduces the severity of havin
 
 ### Token payload
 
-The following fields are included in each ID token:
+The following standard claims are included in each ID token:
+
+| Field                                                              | Description |
+|--------------------------------------------------------------------|-------------|
+| [`iss`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.1) | Issuer of the token, which is the domain of the GitLab instance ("issuer" claim). |
+| [`sub`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.2) | `project_path:{group}/{project}:ref_type:{type}:ref:{branch_name}` ("subject" claim). |
+| [`aud`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.3) | Intended audience for the token ("audience" claim). Specified in the [ID tokens](../yaml/index.md#id_tokens) configuration. The domain of the GitLab instance by default. |
+| [`exp`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.4) | The expiration time ("expiration time" claim). |
+| [`nbf`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.5) | The time after which the token becomes valid ("not before" claim). |
+| [`iat`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.6) | The time the JWT was issued ("issued at" claim). |
+| [`jti`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.7) | Unique identifier for the token ("JWT ID" claim). |
+
+The token also includes custom claims provided by GitLab:
 
 | Field                   | When                         | Description |
 |-------------------------|------------------------------|-------------|
-| [`aud`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.3) | Always | Intended audience for the token ("audience" claim). Configured in GitLab the CI/CD configuration. The domain of the GitLab instance by default. |
-| [`exp`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.4) | Always | The expiration time ("expiration time" claim). |
-| [`iat`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.6) | Always | The time the JWT was issued ("issued at" claim). |
-| [`iss`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.1) | Always | Issuer of the token, which is the domain of the GitLab instance ("issuer" claim). |
-| [`jti`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.7) | Always | Unique identifier for the token ("JWT ID" claim). |
-| [`nbf`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.5) | Always | The time after which the token becomes valid ("not before" claim). |
-| [`sub`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.2) | Always | `project_path:{group}/{project}:ref_type:{type}:ref:{branch_name}` ("subject" claim). |
-| `deployment_tier`       | Job specifies an environment | [Deployment tier](../environments/index.md#deployment-tier-of-environments) of the environment the job specifies. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363590) in GitLab 15.2. |
-| `environment_protected` | Job specifies an environment | `true` if specified environment is protected, `false` otherwise. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294440) in GitLab 13.9. |
-| `environment`           | Job specifies an environment | Environment the job specifies. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294440) in GitLab 13.9. |
-| `job_id`                | Always                       | ID of the job. |
-| `namespace_id`          | Always                       | Use to scope to group or user level namespace by ID. |
-| `namespace_path`        | Always                       | Use to scope to group or user level namespace by path. |
+| `namespace_id`          | Always                       | Use this to scope to group or user level namespace by ID. |
+| `namespace_path`        | Always                       | Use this to scope to group or user level namespace by path. |
+| `project_id`            | Always                       | Use this to scope to project by ID. |
+| `project_path`          | Always                       | Use this to scope to project by path. |
+| `user_id`               | Always                       | ID of the user executing the job. |
+| `user_login`            | Always                       | Username of the user executing the job. |
+| `user_email`            | Always                       | Email of the user executing the job. |
 | `pipeline_id`           | Always                       | ID of the pipeline. |
 | `pipeline_source`       | Always                       | [Pipeline source](../jobs/job_control.md#common-if-clauses-for-rules). |
-| `project_id`            | Always                       | Use to scope to project by ID. |
-| `project_path`          | Always                       | Use to scope to project by path. |
-| `ref_protected`         | Always                       | `true` if the Git ref is protected, `false` otherwise. |
-| `ref_type`              | Always                       | Git ref type, either `branch` or `tag`. |
+| `job_id`                | Always                       | ID of the job. |
 | `ref`                   | Always                       | Git ref for the job. |
-| `user_email`            | Always                       | Email of the user executing the job. |
-| `user_id`               | Always                       | ID of the user executing the job. |
-| `user_login`            | Always                       | Username of the user executing the job. |
-
-Example ID token payload:
+| `ref_type`              | Always                       | Git ref type, either `branch` or `tag`. |
+| `ref_protected`         | Always                       | `true` if the Git ref is protected, `false` otherwise. |
+| `environment`           | Job specifies an environment | Environment this job deploys to ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294440) in GitLab 13.9). |
+| `environment_protected` | Job specifies an environment | `true` if deployed environment is protected, `false` otherwise ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294440) in GitLab 13.9). |
+| `deployment_tier`       | Job specifies an environment | [Deployment tier](../environments/index.md#deployment-tier-of-environments) of the environment the job specifies. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363590) in GitLab 15.2. |
 
 ```json
 {
-  "jti": "c82eeb0c-5c6f-4a33-abf5-4c474b92b558",
-  "aud": "hashicorp.example.com",
-  "iss": "gitlab.example.com",
-  "iat": 1585710286,
-  "nbf": 1585798372,
-  "exp": 1585713886,
-  "sub": "job_1212",
-  "namespace_id": "1",
-  "namespace_path": "mygroup",
-  "project_id": "22",
-  "project_path": "mygroup/myproject",
-  "user_id": "42",
-  "user_login": "myuser",
-  "user_email": "myuser@example.com",
-  "pipeline_id": "1212",
-  "pipeline_source": "web",
-  "job_id": "1212",
-  "ref": "auto-deploy-2020-04-01",
+  "namespace_id": "72",
+  "namespace_path": "my-group",
+  "project_id": "20",
+  "project_path": "my-group/my-project",
+  "user_id": "1",
+  "user_login": "sample-user",
+  "user_email": "sample-user@example.com",
+  "pipeline_id": "574",
+  "pipeline_source": "push",
+  "job_id": "302",
+  "ref": "feature-branch-1",
   "ref_type": "branch",
-  "ref_protected": "true",
-  "environment": "production",
-  "environment_protected": "true"
+  "ref_protected": "false",
+  "environment": "test-environment2",
+  "environment_protected": "false",
+  "deployment_tier": "testing",
+  "jti": "235b3a54-b797-45c7-ae9a-f72d7bc6ef5b",
+  "iss": "https://gitlab.example.com",
+  "iat": 1681395193,
+  "nbf": 1681395188,
+  "exp": 1681398793,
+  "sub": "project_path:my-group/my-project:ref_type:branch:ref:feature-branch-1",
+  "aud": "https://vault.example.com"
 }
 ```
 
diff --git a/doc/user/admin_area/review_abuse_reports.md b/doc/user/admin_area/review_abuse_reports.md
index b8531fded18..314e0c77f36 100644
--- a/doc/user/admin_area/review_abuse_reports.md
+++ b/doc/user/admin_area/review_abuse_reports.md
@@ -1,6 +1,6 @@
 ---
-stage: Manage
-group: Authentication and Authorization
+stage: Anti-Abuse
+group: Anti-Abuse
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
 type: reference, howto
 ---
diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md
index 6f6b4390b7d..05996a70d3d 100644
--- a/doc/user/application_security/policies/index.md
+++ b/doc/user/application_security/policies/index.md
@@ -38,10 +38,6 @@ project and the security policy project, this is not recommended. Keeping the se
 project separate from the development project allows for complete separation of duties between
 security/compliance teams and development teams.
 
-You should not link a security policy project to a development project and to the group
-or sub-group the development project belongs to at the same time. Linking this way will result in
-approval rules from the Scan Result Policy not being applied to merge requests in the development project.
-
 All security policies are stored in the `.gitlab/security-policies/policy.yml` YAML file inside the
 linked security policy project. The format for this YAML is specific to the type of policy that is
 stored there. Examples and schema information are available for the following policy types:
diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md
index 60c36b35b53..1ca558adbc2 100644
--- a/doc/user/clusters/agent/ci_cd_workflow.md
+++ b/doc/user/clusters/agent/ci_cd_workflow.md
@@ -185,6 +185,17 @@ deploy:
   # ... rest of your job configuration
 ```
 
+### Environments with KAS that use self-signed certificates
+
+If you use an environment with KAS and a self-signed certificate, you must configure your Kubernetes client to trust the certificate authority (CA) that signed your certificate.
+
+To configure your client, do one of the following:
+
+- Set a CI/CD variable `SSL_CERT_FILE` with the KAS certificate in PEM format.
+- Configure the Kubernetes client with `--certificate-authority=$KAS_CERTIFICATE`, where `KAS_CERTIFICATE` is a CI/CD variable with the CA certificate of KAS.
+- Place the certificates in an appropriate location in the job container by updating the container image or mounting via the runner.
+- Not recommended. Configure the Kubernetes client with `--insecure-skip-tls-verify=true`.
+
 ## Restrict project and group access by using impersonation **(PREMIUM)**
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345014) in GitLab 14.5.
@@ -342,3 +353,16 @@ If you attempt to use `kubectl` without TLS, you might get an error like:
 $ kubectl get pods
 error: You must be logged in to the server (the server has asked for the client to provide credentials)
 ```
+
+### Unable to connect to the server: certificate signed by unknown authority
+
+If you use an environment with KAS and a self-signed certificate, your `kubectl` call might return this error:
+
+```plaintext
+kubectl get pods
+Unable to connect to the server: x509: certificate signed by unknown authority
+```
+
+The error occurs because the job does not trust the certificate authority (CA) that signed the KAS certificate.
+
+To resolve the issue, [configure `kubectl` to trust the CA](#environments-with-kas-that-use-self-signed-certificates).
diff --git a/doc/user/permissions.md b/doc/user/permissions.md
index 4ca10caef86..f4f205f8499 100644
--- a/doc/user/permissions.md
+++ b/doc/user/permissions.md
@@ -540,3 +540,4 @@ the Owner role:
 
 - Additional permissions can only be applied to users with the Guest role.
 - If a user with a custom role is shared with a group or project, their custom role is not transferred over with them. The user has the regular Guest role in the new group or project.
+- You cannot use an [Auditor user](../administration/auditor_users.md) as a template for a custom role.
diff --git a/doc/user/project/codeowners/index.md b/doc/user/project/codeowners/index.md
index cbf6cc2c186..bbb39179975 100644
--- a/doc/user/project/codeowners/index.md
+++ b/doc/user/project/codeowners/index.md
@@ -58,7 +58,7 @@ GitLab shows the Code Owners at the top of the page.
 ## Set up Code Owners
 
 1. Create a `CODEOWNERS` file in your [preferred location](#code-owners-file).
-1. Define some rules in the file following the [Code Owners syntax reference](#code-owners-syntax-reference).
+1. Define some rules in the file following the [Code Owners syntax reference](reference.md).
    Some suggestions:
    - Configure [All eligible approvers](../merge_requests/approvals/rules.md#code-owners-as-eligible-approvers) approval rule.
    - [Require Code Owner approval](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) on a protected branch.
@@ -337,371 +337,15 @@ The `Documentation` Code Owners section under the **Approval Rules** area displa
 The Code Owner approval and protected branch features do not apply to users who
 are **Allowed to push**.
 
-## Error handling in Code Owners
-
-### Entries with spaces
-
-Paths containing whitespace must be escaped with backslashes: `path\ with\ spaces/*.md`.
-Without the backslashes, the path after the first whitespace is parsed as an owner.
-GitLab the parses `folder with spaces/*.md @group` into
-`path: "folder", owners: " with spaces/*.md @group"`.
-
-### Unparsable sections
-
-If a section heading cannot be parsed, the section is:
-
-1. Parsed as an entry.
-1. Added to the previous section.
-1. If no previous section exists, the section is added to the default section.
-
-For example, this file is missing a square closing bracket:
-
-```plaintext
-* @group
-
-[Section name
-docs/ @docs_group
-```
-
-GitLab recognizes the heading `[Section name` as an entry. The default section includes 3 rules:
-
-- Default section
-  - `*` owned by `@group`
-  - `[Section` owned by `name`
-  - `docs/` owned by `@docs_group`
-
-This file contains an unescaped space between the words `Section` and `name`.
-GitLab recognizes the intended heading as an entry:
-
-```plaintext
-[Docs]
-docs/**/* @group
-
-[Section name]{2} @group
-docs/ @docs_group
-```
-
-The `[Docs]` section then includes 3 rules:
-
-- `docs/**/*` owned by `@group`
-- `[Section` owned by `name]{2} @group`
-- `docs/` owned by `@docs_group`
-
-### Malformed owners
-
-Each entry must contain 1 or more owners to be valid, malformed owners are ignored.
-For example `/path/* @group user_without_at_symbol @user_with_at_symbol`
-is owned by `@group` and `@user_with_at_symbol`.
-
-### Inaccessible or incorrect owners
-
-Inaccessible or incorrect owners are ignored. For example, if `@group`, `@username`,
-and `example@gitlab.com` are accessible on the project and we create an entry:
-
-```plaintext
-* @group @grou @username @i_left @i_dont_exist example@gitlab.com invalid@gitlab.com
-```
-
-GitLab ignores `@grou`, `@i_left`, `@i_dont_exist`, and `invalid@gitlab.com`.
-
-For more information on who is accessible, see [Groups as Code Owners](#groups-as-code-owners).
-
-### Zero owners
-
-If an entry includes no owners, or zero [accessible owners](#inaccessible-or-incorrect-owners)
-exist, the entry is invalid. Because this rule can never be satisfied, GitLab
-auto-approves it in merge requests.
-
-NOTE:
-When a protected branch has `Require code owner approval` enabled, rules with
-zero owners are still honored.
-
-### Less than 1 required approval
-
-When [defining the number of approvals](#require-multiple-approvals-from-code-owners) for a section,
-the minimum number of approvals is `1`. Setting the number of approvals to
-`0` results in GitLab requiring one approval.
-
-## Example `CODEOWNERS` file
-
-```plaintext
-# This is an example of a CODEOWNERS file.
-# Lines that start with `#` are ignored.
-
-# app/ @commented-rule
-
-# Specify a default Code Owner by using a wildcard:
-* @default-codeowner
-
-# Specify multiple Code Owners by using a tab or space:
-* @multiple @code @owners
-
-# Rules defined later in the file take precedence over the rules
-# defined before.
-# For example, for all files with a filename ending in `.rb`:
-*.rb @ruby-owner
-
-# Files with a `#` can still be accessed by escaping the pound sign:
-\#file_with_pound.rb @owner-file-with-pound
-
-# Specify multiple Code Owners separated by spaces or tabs.
-# In the following case the CODEOWNERS file from the root of the repo
-# has 3 Code Owners (@multiple @code @owners):
-CODEOWNERS @multiple @code @owners
-
-# You can use both usernames or email addresses to match
-# users. Everything else is ignored. For example, this code
-# specifies the `@legal` and a user with email `janedoe@gitlab.com` as the
-# owner for the LICENSE file:
-LICENSE @legal this_does_not_match janedoe@gitlab.com
-
-# Use group names to match groups, and nested groups to specify
-# them as owners for a file:
-README @group @group/with-nested/subgroup
-
-# End a path in a `/` to specify the Code Owners for every file
-# nested in that directory, on any level:
-/docs/ @all-docs
-
-# End a path in `/*` to specify Code Owners for every file in
-# a directory, but not nested deeper. This code matches
-# `docs/index.md` but not `docs/projects/index.md`:
-/docs/* @root-docs
-
-# Include `/**` to specify Code Owners for all subdirectories
-# in a directory. This rule matches `docs/projects/index.md` or
-# `docs/development/index.md`
-/docs/**/*.md @root-docs
-
-# This code makes matches a `lib` directory nested anywhere in the repository:
-lib/ @lib-owner
-
-# This code match only a `config` directory in the root of the repository:
-/config/ @config-owner
-
-# If the path contains spaces, escape them like this:
-path\ with\ spaces/ @space-owner
-
-# Code Owners section:
-[Documentation]
-ee/docs    @docs
-docs       @docs
-
-# Use of default owners for a section. In this case, all files (*) are owned by
-the dev team except the README.md and data-models which are owned by other teams.
-[Development] @dev-team
-*
-README.md @docs-team
-data-models/ @data-science-team
-
-# This section is combined with the previously defined [Documentation] section:
-[DOCUMENTATION]
-README.md  @docs
-```
-
-## Code Owners syntax reference
-
-### Comments
-
-Lines beginning with `#` are ignored:
-
-```codeowners
-# This is a comment
-```
-
-### Sections
-
-Sections are groups of entries. A section begins with a section heading in square brackets, followed by the entries.
-
-```codeowners
-[Section name]
-/path/of/protected/file.rb @username
-/path/of/protected/dir/ @group
-```
-
-### Section headings
-
-Section headings must always have a name. They can also be made optional, or require a number of approvals. A list of default owners can be added to the section heading line.
-
-```codeowners
-# Required section
-[Section name]
-
-# Optional section
-^[Section name]
-
-# Section requiring 5 approvals
-[Section name][5]
-
-# Section with @username as default owner
-[Section name] @username
-
-# Section with @group and @subgroup as default owners and requiring 2 approvals
-[Section name][2] @group @subgroup
-```
-
-### Section names
-
-Sections names are defined between square brackets.
-Section names are not case-sensitive. [Sections with duplicate names are combined](#sections-with-duplicate-names).
-
-```codeowners
-[Section name]
-```
-
-### Required sections
-
-Required sections do not include `^` before the [section name](#section-names).
-
-```codeowners
-[Required section]
-```
-
-### Optional sections
-
-Optional sections include a `^` before the [section name](#section-names).
-
-```codeowners
-^[Optional section]
-```
-
-### Sections requiring multiple approvals
-
-Sections requiring multiple approvals include the number of approvals in square brackets after the [section name](#section-names).
-
-```codeowners
-[Section requiring 5 approvals][5]
-```
-
-NOTE:
-Optional sections ignore the number of approvals required.
-
-### Sections with default owners
-
-You can define a default owner for the entries in a section by appending the owners to the [section heading](#section-headings).
-
-```codeowners
-# Section with @username as default owner
-[Section name] @username
-
-# Section with @group and @subgroup as default owners and requiring 2 approvals
-[Section name][2] @group @subgroup
-```
-
-### Code Owner entries
-
-Each Code Owner entry includes a path followed by one or more owners.
-
-```codeowners
-README.md @username1
-```
-
-NOTE:
-If an entry is duplicated in a section, [the last entry is used from each section.](#define-more-specific-owners-for-more-specifically-defined-files-or-directories)
-
-### Relative paths
-
-If a path does not start with a `/`, the path is treated as if it starts with a [globstar](#globstar-paths).
-`README.md` is treated the same way as `/**/README.md`
-
-```codeowners
-# This will match /README.md, /internal/README.md, /app/lib/README.md
-README.md @username
-
-# This will match /internal/README.md, /docs/internal/README.md, /docs/api/internal/README.md
-internal/README.md
-```
-
-### Absolute paths
-
-If a path starts with a `/` it matches the root of the repository.
-
-```codeowners
-# Matches only the file named `README.md` in the root of the repository.
-/README.md
-
-# Matches only the file named `README.md` inside the `/docs` directory.
-/docs/README.md
-```
-
-### Directory paths
-
-If a path ends with `/`, the path matches any file in the directory.
-
-```codeowners
-# This is the same as `/docs/**/*`
-/docs/
-```
-
-### Wildcard paths
-
-Wildcards can be used to match one of more characters of a path.
-
-```codeowners
-# Any markdown files in the docs directory
-/docs/*.md @username
-
-# /docs/index file of any filetype
-# For example: /docs/index.md, /docs/index.html, /docs/index.xml
-/docs/index.* @username
-
-# Any file in the docs directory with 'spec' in the name.
-# For example: /docs/qa_specs.rb, /docs/spec_helpers.rb, /docs/runtime.spec
-/docs/*spec* @username
-
-# README.md files one level deep within the docs directory
-# For example: /docs/api/README.md
-/docs/*/README.md @username
-```
-
-### Globstar paths
-
-Globstars (`**`) can be used to match zero or more directories and subdirectories.
-
-```codeowners
-# This will match /docs/index.md, /docs/api/index.md, /docs/api/graphql/index.md
-/docs/**/index.md
-```
-
-### Entry owners
-
-Entries must be followed by one or more owner, these can be groups, subgroups,
-and users. Order of owners is not important.
-
-```codeowners
-/path/to/entry.rb @group
-/path/to/entry.rb @group/subgroup
-/path/to/entry.rb @user
-/path/to/entry.rb @group @group/subgroup @user
-```
-
-### Groups as entry owners
-
-Groups and subgroups can be owners of an entry.
-Each entry can be owned by [one or more owners](#entry-owners).
-For more details see the [Groups as Code Owners section](#groups-as-code-owners).
-
-```codeowners
-/path/to/entry.rb @group
-/path/to/entry.rb @group/subgroup
-/path/to/entry.rb @group @group/subgroup
-```
-
-### Users as entry owners
-
-Users can be owners of an entry. Each entry can be owned by [one or more owners](#entry-owners).
-
-```codeowners
-/path/to/entry.rb @username1
-/path/to/entry.rb @username1 @username2
-```
-
 ## Technical Resources
 
 [Code Owners development guidelines](../../../development/code_owners/index.md)
 
 ## Troubleshooting
 
+For more information about how the Code Owners feature handles errors, see the
+[Code Owners reference](reference.md).
+
 ### Approvals shown as optional
 
 A Code Owner approval rule is optional if any of these conditions are true:
diff --git a/doc/user/project/codeowners/reference.md b/doc/user/project/codeowners/reference.md
new file mode 100644
index 00000000000..dbb39fafabe
--- /dev/null
+++ b/doc/user/project/codeowners/reference.md
@@ -0,0 +1,371 @@
+---
+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/product/ux/technical-writing/#assignments
+---
+
+# Code Owners syntax and error handling **(PREMIUM)**
+
+This page describes the syntax and error handling used in Code Owners files,
+and provides an example file.
+
+## Code Owners syntax
+
+### Comments
+
+Lines beginning with `#` are ignored:
+
+```plaintext
+# This is a comment
+```
+
+### Sections
+
+Sections are groups of entries. A section begins with a section heading in square brackets, followed by the entries.
+
+```plaintext
+[Section name]
+/path/of/protected/file.rb @username
+/path/of/protected/dir/ @group
+```
+
+#### Section headings
+
+Section headings must always have a name. They can also be made optional, or
+require a number of approvals. A list of default owners can be added to the section heading line.
+
+```plaintext
+# Required section
+[Section name]
+
+# Optional section
+^[Section name]
+
+# Section requiring 5 approvals
+[Section name][5]
+
+# Section with @username as default owner
+[Section name] @username
+
+# Section with @group and @subgroup as default owners and requiring 2 approvals
+[Section name][2] @group @subgroup
+```
+
+#### Section names
+
+Sections names are defined between square brackets. Section names are not case-sensitive.
+[Sections with duplicate names](index.md#sections-with-duplicate-names) are combined.
+
+```plaintext
+[Section name]
+```
+
+#### Required sections
+
+Required sections do not include `^` before the [section name](#section-names).
+
+```plaintext
+[Required section]
+```
+
+#### Optional sections
+
+Optional sections include a `^` before the [section name](#section-names).
+
+```plaintext
+^[Optional section]
+```
+
+#### Sections requiring multiple approvals
+
+Sections requiring multiple approvals include the number of approvals in square brackets after the [section name](#section-names).
+
+```plaintext
+[Section requiring 5 approvals][5]
+```
+
+NOTE:
+Optional sections ignore the number of approvals required.
+
+#### Sections with default owners
+
+You can define a default owner for the entries in a section by appending the owners to the [section heading](#section-headings).
+
+```plaintext
+# Section with @username as default owner
+[Section name] @username
+
+# Section with @group and @subgroup as default owners and requiring 2 approvals
+[Section name][2] @group @subgroup
+```
+
+### Code Owner entries
+
+Each Code Owner entry includes a path followed by one or more owners.
+
+```plaintext
+README.md @username1
+```
+
+NOTE:
+If an entry is duplicated in a section, [the last entry is used from each section.](index.md#define-more-specific-owners-for-more-specifically-defined-files-or-directories)
+
+### Relative paths
+
+If a path does not start with a `/`, the path is treated as if it starts with
+a [globstar](#globstar-paths). `README.md` is treated the same way as `/**/README.md`:
+
+```plaintext
+# This will match /README.md, /internal/README.md, /app/lib/README.md
+README.md @username
+
+# This will match /internal/README.md, /docs/internal/README.md, /docs/api/internal/README.md
+internal/README.md
+```
+
+### Absolute paths
+
+If a path starts with a `/` it matches the root of the repository.
+
+```plaintext
+# Matches only the file named `README.md` in the root of the repository.
+/README.md
+
+# Matches only the file named `README.md` inside the `/docs` directory.
+/docs/README.md
+```
+
+### Directory paths
+
+If a path ends with `/`, the path matches any file in the directory.
+
+```plaintext
+# This is the same as `/docs/**/*`
+/docs/
+```
+
+### Wildcard paths
+
+Wildcards can be used to match one of more characters of a path.
+
+```plaintext
+# Any markdown files in the docs directory
+/docs/*.md @username
+
+# /docs/index file of any filetype
+# For example: /docs/index.md, /docs/index.html, /docs/index.xml
+/docs/index.* @username
+
+# Any file in the docs directory with 'spec' in the name.
+# For example: /docs/qa_specs.rb, /docs/spec_helpers.rb, /docs/runtime.spec
+/docs/*spec* @username
+
+# README.md files one level deep within the docs directory
+# For example: /docs/api/README.md
+/docs/*/README.md @username
+```
+
+### Globstar paths
+
+Globstars (`**`) can be used to match zero or more directories and subdirectories.
+
+```plaintext
+# This will match /docs/index.md, /docs/api/index.md, /docs/api/graphql/index.md
+/docs/**/index.md
+```
+
+### Entry owners
+
+Entries must be followed by one or more owner. These can be groups, subgroups,
+and users. Order of owners is not important.
+
+```plaintext
+/path/to/entry.rb @group
+/path/to/entry.rb @group/subgroup
+/path/to/entry.rb @user
+/path/to/entry.rb @group @group/subgroup @user
+```
+
+#### Groups as entry owners
+
+Groups and subgroups can be owners of an entry.
+Each entry can be owned by [one or more owners](#entry-owners).
+For more details see the [Groups as Code Owners section](index.md#groups-as-code-owners).
+
+```plaintext
+/path/to/entry.rb @group
+/path/to/entry.rb @group/subgroup
+/path/to/entry.rb @group @group/subgroup
+```
+
+### Users as entry owners
+
+Users can be owners of an entry. Each entry can be owned by
+[one or more owners](#entry-owners).
+
+```plaintext
+/path/to/entry.rb @username1
+/path/to/entry.rb @username1 @username2
+```
+
+## Error handling in Code Owners
+
+### Entries with spaces
+
+Paths containing whitespace must be escaped with backslashes: `path\ with\ spaces/*.md`.
+Without the backslashes, the path after the first whitespace is parsed as an owner.
+GitLab the parses `folder with spaces/*.md @group` into
+`path: "folder", owners: " with spaces/*.md @group"`.
+
+### Unparsable sections
+
+If a section heading cannot be parsed, the section is:
+
+1. Parsed as an entry.
+1. Added to the previous section.
+1. If no previous section exists, the section is added to the default section.
+
+For example, this file is missing a square closing bracket:
+
+```plaintext
+* @group
+
+[Section name
+docs/ @docs_group
+```
+
+GitLab recognizes the heading `[Section name` as an entry. The default section includes 3 rules:
+
+- Default section
+  - `*` owned by `@group`
+  - `[Section` owned by `name`
+  - `docs/` owned by `@docs_group`
+
+This file contains an unescaped space between the words `Section` and `name`.
+GitLab recognizes the intended heading as an entry:
+
+```plaintext
+[Docs]
+docs/**/* @group
+
+[Section name]{2} @group
+docs/ @docs_group
+```
+
+The `[Docs]` section then includes 3 rules:
+
+- `docs/**/*` owned by `@group`
+- `[Section` owned by `name]{2} @group`
+- `docs/` owned by `@docs_group`
+
+### Malformed owners
+
+Each entry must contain 1 or more owners to be valid, malformed owners are ignored.
+For example `/path/* @group user_without_at_symbol @user_with_at_symbol`
+is owned by `@group` and `@user_with_at_symbol`.
+
+### Inaccessible or incorrect owners
+
+Inaccessible or incorrect owners are ignored. For example, if `@group`, `@username`,
+and `example@gitlab.com` are accessible on the project and we create an entry:
+
+```plaintext
+* @group @grou @username @i_left @i_dont_exist example@gitlab.com invalid@gitlab.com
+```
+
+GitLab ignores `@grou`, `@i_left`, `@i_dont_exist`, and `invalid@gitlab.com`.
+
+For more information on who is accessible, see [Groups as Code Owners](index.md#groups-as-code-owners).
+
+### Zero owners
+
+If an entry includes no owners, or zero [accessible owners](#inaccessible-or-incorrect-owners)
+exist, the entry is invalid. Because this rule can never be satisfied, GitLab
+auto-approves it in merge requests.
+
+NOTE:
+When a protected branch has `Require code owner approval` enabled, rules with
+zero owners are still honored.
+
+### Less than 1 required approval
+
+When [defining the number of approvals](index.md#require-multiple-approvals-from-code-owners) for a section,
+the minimum number of approvals is `1`. Setting the number of approvals to
+`0` results in GitLab requiring one approval.
+
+## Example `CODEOWNERS` file
+
+```plaintext
+# This is an example of a CODEOWNERS file.
+# Lines that start with `#` are ignored.
+
+# app/ @commented-rule
+
+# Specify a default Code Owner by using a wildcard:
+* @default-codeowner
+
+# Specify multiple Code Owners by using a tab or space:
+* @multiple @code @owners
+
+# Rules defined later in the file take precedence over the rules
+# defined before.
+# For example, for all files with a filename ending in `.rb`:
+*.rb @ruby-owner
+
+# Files with a `#` can still be accessed by escaping the pound sign:
+\#file_with_pound.rb @owner-file-with-pound
+
+# Specify multiple Code Owners separated by spaces or tabs.
+# In the following case the CODEOWNERS file from the root of the repo
+# has 3 Code Owners (@multiple @code @owners):
+CODEOWNERS @multiple @code @owners
+
+# You can use both usernames or email addresses to match
+# users. Everything else is ignored. For example, this code
+# specifies the `@legal` and a user with email `janedoe@gitlab.com` as the
+# owner for the LICENSE file:
+LICENSE @legal this_does_not_match janedoe@gitlab.com
+
+# Use group names to match groups, and nested groups to specify
+# them as owners for a file:
+README @group @group/with-nested/subgroup
+
+# End a path in a `/` to specify the Code Owners for every file
+# nested in that directory, on any level:
+/docs/ @all-docs
+
+# End a path in `/*` to specify Code Owners for every file in
+# a directory, but not nested deeper. This code matches
+# `docs/index.md` but not `docs/projects/index.md`:
+/docs/* @root-docs
+
+# Include `/**` to specify Code Owners for all subdirectories
+# in a directory. This rule matches `docs/projects/index.md` or
+# `docs/development/index.md`
+/docs/**/*.md @root-docs
+
+# This code makes matches a `lib` directory nested anywhere in the repository:
+lib/ @lib-owner
+
+# This code match only a `config` directory in the root of the repository:
+/config/ @config-owner
+
+# If the path contains spaces, escape them like this:
+path\ with\ spaces/ @space-owner
+
+# Code Owners section:
+[Documentation]
+ee/docs    @docs
+docs       @docs
+
+# Use of default owners for a section. In this case, all files (*) are owned by
+the dev team except the README.md and data-models which are owned by other teams.
+[Development] @dev-team
+*
+README.md @docs-team
+data-models/ @data-science-team
+
+# This section is combined with the previously defined [Documentation] section:
+[DOCUMENTATION]
+README.md  @docs
+```
diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md
index 6aac0dba63d..92fdc59dde3 100644
--- a/doc/user/project/deploy_keys/index.md
+++ b/doc/user/project/deploy_keys/index.md
@@ -86,6 +86,7 @@ Prerequisites:
 1. Complete the fields.
 1. Optional. To grant `read-write` permission, select the **Grant write permissions to this key**
    checkbox.
+1. Optional. Update the **Expiration date**.
 
 A project deploy key is enabled when it is created. You can modify only a project deploy key's
 name and permissions.