Add latest changes from gitlab-org/gitlab@master

41 files changed, 1140 insertions, 1036 deletions

diff --git a/doc/administration/auth/atlassian.md b/doc/administration/auth/atlassian.md
index b58bbfa8eac..14c48231a3d 100644
--- a/doc/administration/auth/atlassian.md
+++ b/doc/administration/auth/atlassian.md
@@ -41,7 +41,7 @@ To enable the Atlassian OmniAuth provider for passwordless authentication you mu
    sudo -u git -H editor /home/git/gitlab/config/gitlab.yml
    ```
 
-1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings to enable single sign-on and add `atlassian_oauth2` as an OAuth provider.
+1. See [Configure initial settings](../../integration/omniauth.md#configure-initial-settings) for initial settings to enable single sign-on and add `atlassian_oauth2` as an OAuth provider.
 1. Add the provider configuration for Atlassian:
 
    For Omnibus GitLab installations:
diff --git a/doc/administration/auth/authentiq.md b/doc/administration/auth/authentiq.md
index 835293ff500..19ee143a72a 100644
--- a/doc/administration/auth/authentiq.md
+++ b/doc/administration/auth/authentiq.md
@@ -27,7 +27,7 @@ Authentiq generates a Client ID and the accompanying Client Secret for you to us
    sudo -u git -H editor /home/git/gitlab/config/gitlab.yml
    ```
 
-1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings to enable single sign-on and add Authentiq as an OAuth provider.
+1. See [Configure initial settings](../../integration/omniauth.md#configure-initial-settings) for initial settings to enable single sign-on and add Authentiq as an OAuth provider.
 
 1. Add the provider configuration for Authentiq:
 
diff --git a/doc/administration/auth/cognito.md b/doc/administration/auth/cognito.md
index 41e77c10e27..d137489a838 100644
--- a/doc/administration/auth/cognito.md
+++ b/doc/administration/auth/cognito.md
@@ -40,7 +40,7 @@ The following steps enable AWS Cognito as an authentication provider:
 
 ## Configure GitLab
 
-1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings.
+1. See [Configure initial settings](../../integration/omniauth.md#configure-initial-settings) for initial settings.
 1. On your GitLab server, open the configuration file.
 
    **For Omnibus installations**
@@ -88,4 +88,4 @@ Your sign-in page should now display a Cognito button below the regular sign-in
 To begin the authentication process, click the icon, and AWS Cognito asks the user to sign in and authorize the GitLab application.
 If successful, the user is redirected and signed in to your GitLab instance.
 
-For more information, see the [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration).
+For more information, see [Configure initial settings](../../integration/omniauth.md#configure-initial-settings).
diff --git a/doc/administration/auth/crowd.md b/doc/administration/auth/crowd.md
index f83710ef4c7..d8139b76666 100644
--- a/doc/administration/auth/crowd.md
+++ b/doc/administration/auth/crowd.md
@@ -36,7 +36,7 @@ this provider also allows Crowd authentication for Git-over-https requests.
      sudo -u git -H editor config/gitlab.yml
    ```
 
-1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration)
+1. See [Configure initial settings](../../integration/omniauth.md#configure-initial-settings)
    for initial settings.
 
 1. Add the provider configuration:
diff --git a/doc/administration/auth/jwt.md b/doc/administration/auth/jwt.md
index b74b70ee8c0..26e523cb802 100644
--- a/doc/administration/auth/jwt.md
+++ b/doc/administration/auth/jwt.md
@@ -25,7 +25,7 @@ JWT will provide you with a secret key for you to use.
    sudo -u git -H editor config/gitlab.yml
    ```
 
-1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings.
+1. See [Configure initial settings](../../integration/omniauth.md#configure-initial-settings) for initial settings.
 1. Add the provider configuration.
 
    For Omnibus GitLab:
diff --git a/doc/administration/auth/oidc.md b/doc/administration/auth/oidc.md
index 12729f2050b..d62e5bac630 100644
--- a/doc/administration/auth/oidc.md
+++ b/doc/administration/auth/oidc.md
@@ -27,7 +27,7 @@ The OpenID Connect provides you with a client's details and secret for you to us
    sudo -u git -H editor config/gitlab.yml
    ```
 
-   See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings.
+   See [Configure initial settings](../../integration/omniauth.md#configure-initial-settings) for initial settings.
 
 1. Add the provider configuration.
 
@@ -228,7 +228,7 @@ Azure B2C [offers two ways of defining the business logic for logging in a user]
 
 While cumbersome to configure, custom policies are required because
 standard Azure B2C user flows [do not send the OpenID `email` claim](https://github.com/MicrosoftDocs/azure-docs/issues/16566). In
-other words, they do not work with the [`allow_single_sign_on` or `auto_link_user` parameters](../../integration/omniauth.md#initial-omniauth-configuration).
+other words, they do not work with the [`allow_single_sign_on` or `auto_link_user` parameters](../../integration/omniauth.md#configure-initial-settings).
 With a standard Azure B2C policy, GitLab cannot create a new account or
 link to an existing one with an email address.
 
diff --git a/doc/administration/gitaly/troubleshooting.md b/doc/administration/gitaly/troubleshooting.md
index 1f90ebb7565..d6d93b8af94 100644
--- a/doc/administration/gitaly/troubleshooting.md
+++ b/doc/administration/gitaly/troubleshooting.md
@@ -157,7 +157,7 @@ Confirm the following are all true:
   successfully creates the project but doesn't create the README.
 - When [tailing the logs](https://docs.gitlab.com/omnibus/settings/logs.html#tail-logs-in-a-console-on-the-server)
   on a Gitaly client and reproducing the error, you get `401` errors
-  when reaching the [`/api/v4/internal/allowed`](../../development/internal_api.md) endpoint:
+  when reaching the [`/api/v4/internal/allowed`](../../development/internal_api/index.md) endpoint:
 
   ```shell
   # api_json.log
diff --git a/doc/administration/maintenance_mode/index.md b/doc/administration/maintenance_mode/index.md
index d5bcd132665..2d17062e955 100644
--- a/doc/administration/maintenance_mode/index.md
+++ b/doc/administration/maintenance_mode/index.md
@@ -119,7 +119,7 @@ For most JSON requests, POST, PUT, PATCH, and DELETE are blocked, and the API re
 | POST | `/admin/session`, `/admin/session/destroy` | To allow [Administrator mode for GitLab administrators](https://gitlab.com/groups/gitlab-org/-/epics/2158) |
 | POST | Paths ending with `/compare`| Git revision routes. |
 | POST | `.git/git-upload-pack` | To allow Git pull/clone. |
-| POST | `/api/v4/internal` | [internal API routes](../../development/internal_api.md) |
+| POST | `/api/v4/internal` | [internal API routes](../../development/internal_api/index.md) |
 | POST | `/admin/sidekiq` | To allow management of background jobs in the Admin UI |
 | POST | `/admin/geo` | To allow updating Geo Nodes in the administrator UI |
 | POST | `/api/v4/geo_replication`| To allow certain Geo-specific administrator UI actions on secondary sites |
diff --git a/doc/administration/troubleshooting/debug.md b/doc/administration/troubleshooting/debug.md
index e00243aca0a..744e12d4da1 100644
--- a/doc/administration/troubleshooting/debug.md
+++ b/doc/administration/troubleshooting/debug.md
@@ -258,7 +258,7 @@ separate Rails process to debug the issue:
 ### GitLab: API is not accessible
 
 This often occurs when GitLab Shell attempts to request authorization via the
-[internal API](../../development/internal_api.md) (for example, `http://localhost:8080/api/v4/internal/allowed`), and
+[internal API](../../development/internal_api/index.md) (for example, `http://localhost:8080/api/v4/internal/allowed`), and
 something in the check fails. There are many reasons why this may happen:
 
 1. Timeout connecting to a database (for example, PostgreSQL or Redis)
@@ -275,7 +275,7 @@ strace -ttTfyyy -s 1024 -p <PID of puma worker> -o /tmp/puma.txt
 
 If you cannot isolate which Unicorn worker is the issue, try to run `strace`
 on all the Unicorn workers to see where the
-[`/internal/allowed`](../../development/internal_api.md) endpoint gets stuck:
+[`/internal/allowed`](../../development/internal_api/index.md) endpoint gets stuck:
 
 ```shell
 ps auwx | grep puma | awk '{ print " -p " $2}' | xargs  strace -ttTfyyy -s 1024 -o /tmp/puma.txt
diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md
index 66be4ffff97..63b38e5291b 100644
--- a/doc/api/graphql/reference/index.md
+++ b/doc/api/graphql/reference/index.md
@@ -419,6 +419,22 @@ four standard [pagination arguments](#connection-pagination-arguments):
 | <a id="querytimelogsstarttime"></a>`startTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or after startTime. |
 | <a id="querytimelogsusername"></a>`username` | [`String`](#string) | List timelogs for a user. |
 
+### `Query.topics`
+
+Find project topics.
+
+Returns [`TopicConnection`](#topicconnection).
+
+This field returns a [connection](#connections). It accepts the
+four standard [pagination arguments](#connection-pagination-arguments):
+`before: String`, `after: String`, `first: Int`, `last: Int`.
+
+#### Arguments
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| <a id="querytopicssearch"></a>`search` | [`String`](#string) | Search query for topic name. |
+
 ### `Query.usageTrendsMeasurements`
 
 Get statistics on the instance.
@@ -5676,6 +5692,29 @@ The edge type for [`ContainerRepositoryTag`](#containerrepositorytag).
 | <a id="containerrepositorytagedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. |
 | <a id="containerrepositorytagedgenode"></a>`node` | [`ContainerRepositoryTag`](#containerrepositorytag) | The item at the end of the edge. |
 
+#### `CoverageFuzzingCorpusConnection`
+
+The connection type for [`CoverageFuzzingCorpus`](#coveragefuzzingcorpus).
+
+##### Fields
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| <a id="coveragefuzzingcorpusconnectionedges"></a>`edges` | [`[CoverageFuzzingCorpusEdge]`](#coveragefuzzingcorpusedge) | A list of edges. |
+| <a id="coveragefuzzingcorpusconnectionnodes"></a>`nodes` | [`[CoverageFuzzingCorpus]`](#coveragefuzzingcorpus) | A list of nodes. |
+| <a id="coveragefuzzingcorpusconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. |
+
+#### `CoverageFuzzingCorpusEdge`
+
+The edge type for [`CoverageFuzzingCorpus`](#coveragefuzzingcorpus).
+
+##### Fields
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| <a id="coveragefuzzingcorpusedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. |
+| <a id="coveragefuzzingcorpusedgenode"></a>`node` | [`CoverageFuzzingCorpus`](#coveragefuzzingcorpus) | The item at the end of the edge. |
+
 #### `CustomEmojiConnection`
 
 The connection type for [`CustomEmoji`](#customemoji).
@@ -7690,6 +7729,29 @@ The edge type for [`Todo`](#todo).
 | <a id="todoedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. |
 | <a id="todoedgenode"></a>`node` | [`Todo`](#todo) | The item at the end of the edge. |
 
+#### `TopicConnection`
+
+The connection type for [`Topic`](#topic).
+
+##### Fields
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| <a id="topicconnectionedges"></a>`edges` | [`[TopicEdge]`](#topicedge) | A list of edges. |
+| <a id="topicconnectionnodes"></a>`nodes` | [`[Topic]`](#topic) | A list of nodes. |
+| <a id="topicconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. |
+
+#### `TopicEdge`
+
+The edge type for [`Topic`](#topic).
+
+##### Fields
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| <a id="topicedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. |
+| <a id="topicedgenode"></a>`node` | [`Topic`](#topic) | The item at the end of the edge. |
+
 #### `TreeConnection`
 
 The connection type for [`Tree`](#tree).
@@ -8991,6 +9053,17 @@ A tag from a container repository.
 | <a id="containerrepositorytagshortrevision"></a>`shortRevision` | [`String`](#string) | Short revision of the tag. |
 | <a id="containerrepositorytagtotalsize"></a>`totalSize` | [`BigInt`](#bigint) | Size of the tag. |
 
+### `CoverageFuzzingCorpus`
+
+Corpus for a coverage fuzzing job.
+
+#### Fields
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| <a id="coveragefuzzingcorpusid"></a>`id` | [`AppSecFuzzingCoverageCorpusID!`](#appsecfuzzingcoveragecorpusid) | ID of the corpus. |
+| <a id="coveragefuzzingcorpuspackage"></a>`package` | [`PackageDetailsType!`](#packagedetailstype) | Package of the corpus. |
+
 ### `CurrentLicense`
 
 Represents the current license.
@@ -12763,6 +12836,7 @@ Represents vulnerability finding of a security report on the pipeline.
 | <a id="projectcontainerexpirationpolicy"></a>`containerExpirationPolicy` | [`ContainerExpirationPolicy`](#containerexpirationpolicy) | Container expiration policy of the project. |
 | <a id="projectcontainerregistryenabled"></a>`containerRegistryEnabled` | [`Boolean`](#boolean) | Indicates if Container Registry is enabled for the current user. |
 | <a id="projectcontainerrepositoriescount"></a>`containerRepositoriesCount` | [`Int!`](#int) | Number of container repositories in the project. |
+| <a id="projectcorpuses"></a>`corpuses` | [`CoverageFuzzingCorpusConnection`](#coveragefuzzingcorpusconnection) | Find corpuses of the project. Available only when feature flag `corpus_management` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. (see [Connections](#connections)) |
 | <a id="projectcreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp of the project creation. |
 | <a id="projectdastscannerprofiles"></a>`dastScannerProfiles` | [`DastScannerProfileConnection`](#dastscannerprofileconnection) | DAST scanner profiles associated with the project. (see [Connections](#connections)) |
 | <a id="projectdastsiteprofiles"></a>`dastSiteProfiles` | [`DastSiteProfileConnection`](#dastsiteprofileconnection) | DAST Site Profiles associated with the project. (see [Connections](#connections)) |
@@ -14807,6 +14881,18 @@ Representing a to-do entry.
 | <a id="todostate"></a>`state` | [`TodoStateEnum!`](#todostateenum) | State of the to-do item. |
 | <a id="todotargettype"></a>`targetType` | [`TodoTargetEnum!`](#todotargetenum) | Target type of the to-do item. |
 
+### `Topic`
+
+#### Fields
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| <a id="topicavatarurl"></a>`avatarUrl` | [`String`](#string) | URL to avatar image file of the topic. |
+| <a id="topicdescription"></a>`description` | [`String`](#string) | Description of the topic. |
+| <a id="topicdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. |
+| <a id="topicid"></a>`id` | [`ID!`](#id) | ID of the topic. |
+| <a id="topicname"></a>`name` | [`String!`](#string) | Name of the topic. |
+
 ### `Tree`
 
 #### Fields
@@ -16819,6 +16905,7 @@ State of a Sentry error.
 | <a id="servicetypeprometheus_service"></a>`PROMETHEUS_SERVICE` | PrometheusService type. |
 | <a id="servicetypepushover_service"></a>`PUSHOVER_SERVICE` | PushoverService type. |
 | <a id="servicetyperedmine_service"></a>`REDMINE_SERVICE` | RedmineService type. |
+| <a id="servicetypeshimo_service"></a>`SHIMO_SERVICE` | ShimoService type. |
 | <a id="servicetypeslack_service"></a>`SLACK_SERVICE` | SlackService type. |
 | <a id="servicetypeslack_slash_commands_service"></a>`SLACK_SLASH_COMMANDS_SERVICE` | SlackSlashCommandsService type. |
 | <a id="servicetypeteamcity_service"></a>`TEAMCITY_SERVICE` | TeamcityService type. |
@@ -17137,6 +17224,12 @@ A `AnalyticsDevopsAdoptionEnabledNamespaceID` is a global ID. It is encoded as a
 
 An example `AnalyticsDevopsAdoptionEnabledNamespaceID` is: `"gid://gitlab/Analytics::DevopsAdoption::EnabledNamespace/1"`.
 
+### `AppSecFuzzingCoverageCorpusID`
+
+A `AppSecFuzzingCoverageCorpusID` is a global ID. It is encoded as a string.
+
+An example `AppSecFuzzingCoverageCorpusID` is: `"gid://gitlab/AppSec::Fuzzing::Coverage::Corpus/1"`.
+
 ### `AuditEventsExternalAuditEventDestinationID`
 
 A `AuditEventsExternalAuditEventDestinationID` is a global ID. It is encoded as a string.
diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md
index 25fdf40377d..5d591243726 100644
--- a/doc/ci/yaml/index.md
+++ b/doc/ci/yaml/index.md
@@ -426,8 +426,11 @@ Use `include:local` instead of symbolic links.
 
 **Keyword type**: Global keyword.
 
-**Possible inputs**: A full path relative to the root directory (`/`).
-The YAML file must have the extension `.yml` or `.yaml`. Wildcard paths (`*` and `**`) are supported.
+**Possible inputs**:
+
+- A full path relative to the root directory (`/`).
+- The YAML file must have the extension `.yml` or `.yaml`.
+- You can [use `*` and `**` wildcards in the file path](includes.md#use-includelocal-with-wildcard-file-paths).
 
 **Example of `include:local`**:
 
@@ -449,10 +452,6 @@ include: '.gitlab-ci-production.yml'
 - All [nested includes](includes.md#use-nested-includes) are executed in the scope of the same project,
   so you can use local, project, remote, or template includes.
 
-**Related topics**:
-
-- [Use `include:local` with wildcard file paths](includes.md#use-includelocal-with-wildcard-file-paths).
-
 #### `include:file`
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53903) in GitLab 11.7.
diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md
index 73814399d2e..df2f3c337cd 100644
--- a/doc/development/api_styleguide.md
+++ b/doc/development/api_styleguide.md
@@ -240,7 +240,7 @@ it's own file in the [`validators`](https://gitlab.com/gitlab-org/gitlab/-/blob/
 
 ## Internal API
 
-The [internal API](internal_api.md) is documented for internal use. Please keep it up to date so we know what endpoints
+The [internal API](internal_api/index.md) is documented for internal use. Please keep it up to date so we know what endpoints
 different components are making use of.
 
 ## Avoiding N+1 problems
diff --git a/doc/development/architecture.md b/doc/development/architecture.md
index c21b77bc34a..38d0d5d7843 100644
--- a/doc/development/architecture.md
+++ b/doc/development/architecture.md
@@ -976,12 +976,12 @@ in Rails, scheduled to run whenever an SSH key is modified by a user.
 instead of keys. In this case, `AuthorizedKeysCommand` is replaced with an
 `AuthorizedPrincipalsCommand`. This extracts a username from the certificate
 without using the Rails internal API, which is used instead of `key_id` in the
-[`/api/internal/allowed`](internal_api.md) call later.
+[`/api/internal/allowed`](internal_api/index.md) call later.
 
 GitLab Shell also has a few operations that do not involve Gitaly, such as
 resetting two-factor authentication codes. These are handled in the same way,
 except there is no round-trip into Gitaly - Rails performs the action as part
-of the [internal API](internal_api.md) call, and GitLab Shell streams the
+of the [internal API](internal_api/index.md) call, and GitLab Shell streams the
 response back to the user directly.
 
 ## System layout
diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md
index b3d3e2641b7..03980a42381 100644
--- a/doc/development/documentation/restful_api_styleguide.md
+++ b/doc/development/documentation/restful_api_styleguide.md
@@ -49,8 +49,8 @@ METHOD /endpoint
 
 Supported attributes:
 
-| Attribute   | Type     | Required | Description           |
-|:------------|:---------|:---------|:----------------------|
+| Attribute   | Type     | Required               | Description           |
+| :---------- | :------- | :--------------------- | :-------------------- |
 | `attribute` | datatype | **{check-circle}** Yes | Detailed description. |
 | `attribute` | datatype | **{dotted-circle}** No | Detailed description. |
 | `attribute` | datatype | **{dotted-circle}** No | Detailed description. |
@@ -80,16 +80,23 @@ to describe the GitLab release that introduced the API call.
 Use the following table headers to describe the methods. Attributes should
 always be in code blocks using backticks (`` ` ``).
 
+Sort the attributes in the table: first, required, then alphabetically.
+
 ```markdown
-| Attribute | Type | Required | Description |
-|:----------|:-----|:---------|:------------|
+| Attribute      | Type          | Required               | Description                                          |
+| :------------- | :------------ | :--------------------- | :--------------------------------------------------- |
+| `user`         | string        | **{check-circle}** Yes | The GitLab username.                                 |
+| `assignee_ids` | integer array | **{dotted-circle}** No | The IDs of the users to assign the issue to.         |
+| `confidential` | boolean       | **{dotted-circle}** No | Set an issue to be confidential. Default is `false`. |
 ```
 
 Rendered example:
 
-| Attribute | Type   | Required | Description         |
-|:----------|:-------|:---------|:--------------------|
-| `user`    | string | yes      | The GitLab username. |
+| Attribute      | Type          | Required               | Description                                          |
+| :------------- | :------------ | :--------------------- | :--------------------------------------------------- |
+| `user`         | string        | **{check-circle}** Yes | The GitLab username.                                 |
+| `assignee_ids` | integer array | **{dotted-circle}** No | The IDs of the users to assign the issue to.         |
+| `confidential` | boolean       | **{dotted-circle}** No | Set an issue to be confidential. Default is `false`. |
 
 ## cURL commands
 
@@ -101,12 +108,12 @@ Rendered example:
 - Prefer to use examples using the personal access token and don't pass data of
   username and password.
 
-| Methods                                         | Description                                           |
-|:-------------------------------------------     |:------------------------------------------------------|
+| Methods                                         | Description                                            |
+| :---------------------------------------------- | :----------------------------------------------------- |
 | `--header "PRIVATE-TOKEN: <your_access_token>"` | Use this method as is, whenever authentication needed. |
-| `--request POST`                                | Use this method when creating new objects             |
-| `--request PUT`                                 | Use this method when updating existing objects        |
-| `--request DELETE`                              | Use this method when removing existing objects        |
+| `--request POST`                                | Use this method when creating new objects              |
+| `--request PUT`                                 | Use this method when updating existing objects         |
+| `--request DELETE`                              | Use this method when removing existing objects         |
 
 ## cURL Examples
 
diff --git a/doc/development/internal_api.md b/doc/development/internal_api.md
index 652fd69622b..cd2e20bbb49 100644
--- a/doc/development/internal_api.md
+++ b/doc/development/internal_api.md
@@ -1,829 +1,9 @@
 ---
-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, api
+redirect_to: 'internal_api/index.md'
+remove_date: '2022-02-09'
 ---
 
-# Internal API **(FREE)**
+This document was moved to [another location](internal_api/index.md).
 
-The internal API is used by different GitLab components, it can not be
-used by other consumers. This documentation is intended for people
-working on the GitLab codebase.
-
-This documentation does not yet include the internal API used by
-GitLab Pages.
-
-## Adding new endpoints
-
-API endpoints should be externally accessible by default, with proper authentication and authorization.
-Before adding a new internal endpoint, consider if the API would potentially be
-useful to the wider GitLab community and can be made externally accessible.
-
-One reason we might favor internal API endpoints sometimes is when using such an endpoint requires
-internal data that external actors can not have. For example, in the internal Pages API we might use
-a secret token that identifies a request as internal or sign a request with a public key that is
-not available to a wider community.
-
-Another reason to separate something into an internal API is when request to such API endpoint
-should never go through an edge (public) load balancer. This way we can configure different rate
-limiting rules and policies around how the endpoint is being accessed, because we know that only
-internal requests can be made to that endpoint going through an internal load balancer.
-
-## Authentication
-
-These methods are all authenticated using a shared secret. This secret
-is stored in a file at the path configured in `config/gitlab.yml` by
-default this is in the root of the rails app named
-`.gitlab_shell_secret`
-
-To authenticate using that token, clients read the contents of that
-file, and include the token Base64 encoded in a `secret_token` parameter
-or in the `Gitlab-Shared-Secret` header.
-
-NOTE:
-The internal API used by GitLab Pages, and GitLab Kubernetes Agent Server (`kas`) uses JSON Web Token (JWT)
-authentication, which is different from GitLab Shell.
-
-## Git Authentication
-
-This is called by [Gitaly](https://gitlab.com/gitlab-org/gitaly) and
-[GitLab Shell](https://gitlab.com/gitlab-org/gitlab-shell) to check access to a
-repository.
-
-- **When called from GitLab Shell**: No changes are passed, and the internal
-  API replies with the information needed to pass the request on to Gitaly.
-- **When called from Gitaly in a `pre-receive` hook**: The changes are passed
-  and validated to determine if the push is allowed.
-
-Calls are limited to 50 seconds each.
-
-```plaintext
-POST /internal/allowed
-```
-
-| Attribute | Type   | Required | Description |
-|:----------|:-------|:---------|:------------|
-| `key_id`  | string | no       | ID of the SSH-key used to connect to GitLab Shell |
-| `username` | string | no      | Username from the certificate used to connect to GitLab Shell |
-| `project`  | string | no (if `gl_repository` is passed) | Path to the project |
-| `gl_repository`  | string | no (if `project` is passed) | Repository identifier, such as `project-7` |
-| `protocol` | string | yes     | SSH when called from GitLab Shell, HTTP or SSH when called from Gitaly |
-| `action`   | string | yes     | Git command being run (`git-upload-pack`, `git-receive-pack`, `git-upload-archive`) |
-| `changes`  | string | yes     | `<oldrev> <newrev> <refname>` when called from Gitaly, the magic string `_any` when called from GitLab Shell |
-| `check_ip` | string | no     | IP address from which call to GitLab Shell was made |
-
-Example request:
-
-```shell
-curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded token>" \
-     --data "key_id=11&project=gnuwget/wget2&action=git-upload-pack&protocol=ssh" \
-     "http://localhost:3001/api/v4/internal/allowed"
-```
-
-Example response:
-
-```json
-{
-  "status": true,
-  "gl_repository": "project-3",
-  "gl_project_path": "gnuwget/wget2",
-  "gl_id": "user-1",
-  "gl_username": "root",
-  "git_config_options": [],
-  "gitaly": {
-    "repository": {
-      "storage_name": "default",
-      "relative_path": "@hashed/4e/07/4e07408562bedb8b60ce05c1decfe3ad16b72230967de01f640b7e4729b49fce.git",
-      "git_object_directory": "",
-      "git_alternate_object_directories": [],
-      "gl_repository": "project-3",
-      "gl_project_path": "gnuwget/wget2"
-    },
-    "address": "unix:/Users/bvl/repos/gitlab/gitaly.socket",
-    "token": null
-  },
-  "gl_console_messages": []
-}
-```
-
-### Known consumers
-
-- Gitaly
-- GitLab Shell
-
-## LFS Authentication
-
-This is the endpoint that gets called from GitLab Shell to provide
-information for LFS clients when the repository is accessed over SSH.
-
-| Attribute | Type   | Required | Description |
-|:----------|:-------|:---------|:------------|
-| `key_id`  | string | no       | ID of the SSH-key used to connect to GitLab Shell |
-| `username`| string | no       | Username from the certificate used to connect to GitLab Shell |
-| `project` | string | no       | Path to the project |
-
-Example request:
-
-```shell
-curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded token>" \
-     --data "key_id=11&project=gnuwget/wget2" "http://localhost:3001/api/v4/internal/lfs_authenticate"
-```
-
-```json
-{
-  "username": "root",
-  "lfs_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7ImFjdG9yIjoicm9vdCJ9LCJqdGkiOiIyYWJhZDcxZC0xNDFlLTQ2NGUtOTZlMi1mODllYWRiMGVmZTYiLCJpYXQiOjE1NzAxMTc2NzYsIm5iZiI6MTU3MDExNzY3MSwiZXhwIjoxNTcwMTE5NDc2fQ.g7atlBw1QMY7QEBVPE0LZ8ZlKtaRzaMRmNn41r2YITM",
-  "repository_http_path": "http://localhost:3001/gnuwget/wget2.git",
-  "expires_in": 1800
-}
-```
-
-### Known consumers
-
-- GitLab Shell
-
-## Authorized Keys Check
-
-This endpoint is called by the GitLab Shell authorized keys
-check. Which is called by OpenSSH for [fast SSH key
-lookup](../administration/operations/fast_ssh_key_lookup.md).
-
-| Attribute | Type   | Required | Description |
-|:----------|:-------|:---------|:------------|
-| `key`     | string | yes      | SSH key as passed by OpenSSH to GitLab Shell |
-
-```plaintext
-GET /internal/authorized_keys
-```
-
-Example request:
-
-```shell
-curl --request GET --header "Gitlab-Shared-Secret: <Base64 encoded secret>" "http://localhost:3001/api/v4/internal/authorized_keys?key=<key as passed by OpenSSH>"
-```
-
-Example response:
-
-```json
-{
-  "id": 11,
-  "title": "admin@example.com",
-  "key": "ssh-rsa ...",
-  "created_at": "2019-06-27T15:29:02.219Z"
-}
-```
-
-### Known consumers
-
-- GitLab Shell
-
-## Get user for user ID or key
-
-This endpoint is used when a user performs `ssh git@gitlab.com`. It
-discovers the user associated with an SSH key.
-
-| Attribute | Type   | Required | Description |
-|:----------|:-------|:---------|:------------|
-| `key_id` | integer | no | The ID of the SSH key used as found in the authorized-keys file or through the `/authorized_keys` check |
-| `username` | string | no | Username of the user being looked up, used by GitLab Shell when authenticating using a certificate |
-
-```plaintext
-GET /internal/discover
-```
-
-Example request:
-
-```shell
-curl --request GET --header "Gitlab-Shared-Secret: <Base64 encoded secret>" "http://localhost:3001/api/v4/internal/discover?key_id=7"
-```
-
-Example response:
-
-```json
-{
-  "id": 7,
-  "name": "Dede Eichmann",
-  "username": "rubi"
-}
-```
-
-### Known consumers
-
-- GitLab Shell
-
-## Instance information
-
-This gets some generic information about the instance. This is used
-by Geo nodes to get information about each other.
-
-```plaintext
-GET /internal/check
-```
-
-Example request:
-
-```shell
-curl --request GET --header "Gitlab-Shared-Secret: <Base64 encoded secret>" "http://localhost:3001/api/v4/internal/check"
-```
-
-Example response:
-
-```json
-{
-  "api_version": "v4",
-  "gitlab_version": "12.3.0-pre",
-  "gitlab_rev": "d69c988e6a6",
-  "redis": true
-}
-```
-
-### Known consumers
-
-- GitLab Geo
-- GitLab Shell's `bin/check`
-- Gitaly
-
-## Get new 2FA recovery codes using an SSH key
-
-This is called from GitLab Shell and allows users to get new 2FA
-recovery codes based on their SSH key.
-
-| Attribute | Type   | Required | Description |
-|:----------|:-------|:---------|:------------|
-| `key_id`  | integer | no | The ID of the SSH key used as found in the authorized-keys file or through the `/authorized_keys` check |
-| `user_id` | integer | no | **Deprecated** User_id for which to generate new recovery codes |
-
-```plaintext
-GET /internal/two_factor_recovery_codes
-```
-
-Example request:
-
-```shell
-curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" \
-     --data "key_id=7" "http://localhost:3001/api/v4/internal/two_factor_recovery_codes"
-```
-
-Example response:
-
-```json
-{
-  "success": true,
-  "recovery_codes": [
-    "d93ee7037944afd5",
-    "19d7b84862de93dd",
-    "1e8c52169195bf71",
-    "be50444dddb7ca84",
-    "26048c77d161d5b7",
-    "482d5c03d1628c47",
-    "d2c695e309ce7679",
-    "dfb4748afc4f12a7",
-    "0e5f53d1399d7979",
-    "af04d5622153b020"
-  ]
-}
-```
-
-### Known consumers
-
-- GitLab Shell
-
-## Get new personal access-token
-
-This is called from GitLab Shell and allows users to generate a new
-personal access token.
-
-| Attribute | Type   | Required | Description |
-|:----------|:-------|:---------|:------------|
-| `name` | string | yes | The name of the new token |
-| `scopes` | string array | yes | The authorization scopes for the new token, these must be valid token scopes |
-| `expires_at` | string | no | The expiry date for the new token |
-| `key_id`  | integer | no | The ID of the SSH key used as found in the authorized-keys file or through the `/authorized_keys` check |
-| `user_id` | integer | no | User ID for which to generate the new token |
-
-```plaintext
-POST /internal/personal_access_token
-```
-
-Example request:
-
-```shell
-curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" \
-     --data "user_id=29&name=mytokenname&scopes[]=read_user&scopes[]=read_repository&expires_at=2020-07-24" \
-     "http://localhost:3001/api/v4/internal/personal_access_token"
-```
-
-Example response:
-
-```json
-{
-  "success": true,
-  "token": "Hf_79B288hRv_3-TSD1R",
-  "scopes": ["read_user","read_repository"],
-  "expires_at": "2020-07-24"
-}
-```
-
-### Known consumers
-
-- GitLab Shell
-
-## Incrementing counter on pre-receive
-
-This is called from the Gitaly hooks increasing the reference counter
-for a push that might be accepted.
-
-| Attribute | Type   | Required | Description |
-|:----------|:-------|:---------|:------------|
-| `gl_repository` | string | yes | repository identifier for the repository receiving the push |
-
-```plaintext
-POST /internal/pre_receive
-```
-
-Example request:
-
-```shell
-curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" \
-     --data "gl_repository=project-7" "http://localhost:3001/api/v4/internal/pre_receive"
-```
-
-Example response:
-
-```json
-{
-  "reference_counter_increased": true
-}
-```
-
-## PostReceive
-
-Called from Gitaly after a receiving a push. This triggers the
-`PostReceive`-worker in Sidekiq, processes the passed push options and
-builds the response including messages that need to be displayed to
-the user.
-
-| Attribute | Type   | Required | Description |
-|:----------|:-------|:---------|:------------|
-| `identifier` | string | yes | `user-[id]` or `key-[id]` Identifying the user performing the push |
-| `gl_repository` | string | yes | identifier of the repository being pushed to |
-| `push_options` | string array | no | array of push options |
-| `changes` | string | no | refs to be updated in the push in the format `oldrev newrev refname\n`. |
-
-```plaintext
-POST /internal/post_receive
-```
-
-Example Request:
-
-```shell
-curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" \
-     --data "gl_repository=project-7" --data "identifier=user-1" \
-     --data "changes=0000000000000000000000000000000000000000 fd9e76b9136bdd9fe217061b497745792fe5a5ee gh-pages\n" \
-     "http://localhost:3001/api/v4/internal/post_receive"
-```
-
-Example response:
-
-```json
-{
-  "messages": [
-    {
-      "message": "Hello from post-receive",
-      "type": "alert"
-    }
-  ],
-  "reference_counter_decreased": true
-}
-```
-
-## Kubernetes agent endpoints
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41045) in GitLab 13.4.
-> - This feature is not deployed on GitLab.com
-> - It's not recommended for production use.
-
-The following endpoints are used by the GitLab Kubernetes Agent Server (`kas`)
-for various purposes.
-
-These endpoints are all authenticated using JWT. The JWT secret is stored in a file
-specified in `config/gitlab.yml`. By default, the location is in the root of the
-GitLab Rails app in a file called `.gitlab_kas_secret`.
-
-WARNING:
-The Kubernetes agent is under development and is not recommended for production use.
-
-### Kubernetes agent information
-
-Called from GitLab Kubernetes Agent Server (`kas`) to retrieve agent
-information for the given agent token. This returns the Gitaly connection
-information for the agent's project in order for `kas` to fetch and update
-the agent's configuration.
-
-```plaintext
-GET /internal/kubernetes/agent_info
-```
-
-Example Request:
-
-```shell
-curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \
-     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/agent_info"
-```
-
-### Kubernetes agent project information
-
-Called from GitLab Kubernetes Agent Server (`kas`) to retrieve project
-information for the given agent token. This returns the Gitaly
-connection for the requested project. GitLab `kas` uses this to configure
-the agent to fetch Kubernetes resources from the project repository to
-sync.
-
-Only public projects are supported. For private projects, the ability for the
-agent to be authorized is [not yet implemented](https://gitlab.com/gitlab-org/gitlab/-/issues/220912).
-
-| Attribute | Type   | Required | Description |
-|:----------|:-------|:---------|:------------|
-| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../api/index.md#namespaced-path-encoding) |
-
-```plaintext
-GET /internal/kubernetes/project_info
-```
-
-Example Request:
-
-```shell
-curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \
-     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/project_info?id=7"
-```
-
-### Kubernetes agent usage metrics
-
-Called from GitLab Kubernetes Agent Server (`kas`) to increase the usage
-metric counters.
-
-| Attribute | Type   | Required | Description |
-|:----------|:-------|:---------|:------------|
-| `gitops_sync_count` | integer| no | The number to increase the `gitops_sync_count` counter by |
-| `k8s_api_proxy_request_count` | integer| no | The number to increase the `k8s_api_proxy_request_count` counter by |
-
-```plaintext
-POST /internal/kubernetes/usage_metrics
-```
-
-Example Request:
-
-```shell
-curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" --header "Content-Type: application/json" \
-     --data '{"gitops_sync_count":1}' "http://localhost:3000/api/v4/internal/kubernetes/usage_metrics"
-```
-
-### Kubernetes agent alert metrics
-
-Called from GitLab Kubernetes Agent Server (KAS) to save alerts derived from Cilium on Kubernetes
-Cluster.
-
-| Attribute | Type   | Required | Description |
-|:----------|:-------|:---------|:------------|
-| `alert` | Hash | yes | Alerts detail. Same format as [3rd party alert](../operations/incident_management/integrations.md#customize-the-alert-payload-outside-of-gitlab). |
-
-```plaintext
-POST internal/kubernetes/modules/cilium_alert
-```
-
-Example Request:
-
-```shell
-curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" \
-     --header "Authorization: Bearer <agent token>" --header "Content-Type: application/json" \
-     --data '"{\"alert\":{\"title\":\"minimal\",\"message\":\"network problem\",\"evalMatches\":[{\"value\":1,\"metric\":\"Count\",\"tags\":{}}]}}"' \
-     "http://localhost:3000/api/v4/internal/kubernetes/modules/cilium_alert"
-```
-
-### Create Starboard vulnerability
-
-Called from the GitLab Kubernetes Agent Server (`kas`) to create a security vulnerability
-from a Starboard vulnerability report. This request is idempotent. Multiple requests with the same data
-create a single vulnerability.
-
-| Attribute       | Type   | Required | Description |
-|:----------------|:-------|:---------|:------------|
-| `vulnerability` | Hash   | yes      | Vulnerability data matching the security report schema [`vulnerability` field](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/src/security-report-format.json). |
-| `scanner`       | Hash   | yes      | Scanner data matching the security report schema [`scanner` field](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/src/security-report-format.json). |
-
-```plaintext
-PUT internal/kubernetes/modules/starboard_vulnerability
-```
-
-Example Request:
-
-```shell
-curl --request PUT --header "Gitlab-Kas-Api-Request: <JWT token>" \
-     --header "Authorization: Bearer <agent token>" --header "Content-Type: application/json" \
-     --url "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability" \
-     --data '{
-  "vulnerability": {
-    "name": "CVE-123-4567 in libc",
-    "severity": "high",
-    "confidence": "unknown",
-    "location": {
-      "kubernetes_resource": {
-        "namespace": "production",
-        "kind": "deployment",
-        "name": "nginx",
-        "container": "nginx"
-      }
-    },
-    "identifiers": [
-      {
-        "type": "cve",
-        "name": "CVE-123-4567",
-        "value": "CVE-123-4567"
-      }
-    ]
-  },
-  "scanner": {
-    "id": "starboard_trivy",
-    "name": "Trivy (via Starboard Operator)",
-    "vendor": "GitLab"
-  }
-}'
-```
-
-## Subscriptions
-
-The subscriptions endpoint is used by [CustomersDot](https://gitlab.com/gitlab-org/customers-gitlab-com) (`customers.gitlab.com`)
-in order to apply subscriptions including trials, and add-on purchases, for personal namespaces or top-level groups within GitLab.com.
-
-### Creating a subscription
-
-Use a POST to create a subscription.
-
-```plaintext
-POST /namespaces/:id/gitlab_subscription
-```
-
-| Attribute   | Type    | Required | Description |
-|:------------|:--------|:---------|:------------|
-| `start_date` | date   | yes      | Start date of subscription |
-| `end_date`  | date    | no       | End date of subscription |
-| `plan_code` | string  | no       | Subscription tier code |
-| `seats`     | integer | no       | Number of seats in subscription |
-| `max_seats_used` | integer | no  | Highest number of active users in the last month |
-| `auto_renew` | boolean | no      | Whether subscription auto-renews on end date |
-| `trial`     | boolean | no       | Whether subscription is a trial |
-| `trial_starts_on` | date | no    | Start date of trial |
-| `trial_ends_on` | date | no      | End date of trial |
-
-Example request:
-
-```shell
-curl --request POST --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription?start_date="2020-07-15"&plan="premium"&seats=10"
-```
-
-Example response:
-
-```json
-{
-  "plan": {
-    "code":"premium",
-    "name":"premium",
-    "trial":false,
-    "auto_renew":null,
-    "upgradable":false
-  },
-  "usage": {
-    "seats_in_subscription":10,
-    "seats_in_use":1,
-    "max_seats_used":0,
-    "seats_owed":0
-  },
-  "billing": {
-    "subscription_start_date":"2020-07-15",
-    "subscription_end_date":null,
-    "trial_ends_on":null
-  }
-}
-```
-
-### Updating a subscription
-
-Use a PUT command to update an existing subscription.
-
-```plaintext
-PUT /namespaces/:id/gitlab_subscription
-```
-
-| Attribute   | Type    | Required | Description |
-|:------------|:--------|:---------|:------------|
-| `start_date` | date   | no       | Start date of subscription |
-| `end_date`  | date    | no       | End date of subscription |
-| `plan_code` | string  | no       | Subscription tier code |
-| `seats`     | integer | no       | Number of seats in subscription |
-| `max_seats_used` | integer | no  | Highest number of active users in the last month |
-| `auto_renew` | boolean | no      | Whether subscription auto-renews on end date |
-| `trial`     | boolean | no       | Whether subscription is a trial |
-| `trial_starts_on` | date | no    | Start date of trial. Required if trial is true. |
-| `trial_ends_on` | date | no      | End date of trial |
-
-Example request:
-
-```shell
-curl --request PUT --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription?max_seats_used=0"
-```
-
-Example response:
-
-```json
-{
-  "plan": {
-    "code":"premium",
-    "name":"premium",
-    "trial":false,
-    "auto_renew":null,
-    "upgradable":false
-  },
-  "usage": {
-    "seats_in_subscription":80,
-    "seats_in_use":82,
-    "max_seats_used":0,
-    "seats_owed":2
-  },
-  "billing": {
-    "subscription_start_date":"2020-07-15",
-    "subscription_end_date":"2021-07-15",
-    "trial_ends_on":null
-  }
-}
-```
-
-### Retrieving a subscription
-
-Use a GET command to view an existing subscription.
-
-```plaintext
-GET /namespaces/:id/gitlab_subscription
-```
-
-Example request:
-
-```shell
-curl --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription"
-```
-
-Example response:
-
-```json
-{
-  "plan": {
-    "code":"premium",
-    "name":"premium",
-    "trial":false,
-    "auto_renew":null,
-    "upgradable":false
-  },
-  "usage": {
-    "seats_in_subscription":80,
-    "seats_in_use":82,
-    "max_seats_used":82,
-    "seats_owed":2
-  },
-  "billing": {
-    "subscription_start_date":"2020-07-15",
-    "subscription_end_date":"2021-07-15",
-    "trial_ends_on":null
-  }
-}
-```
-
-### Known consumers
-
-- CustomersDot
-
-## CI minute provisioning
-
-The CI Minute endpoints are used by [CustomersDot](https://gitlab.com/gitlab-org/customers-gitlab-com) (`customers.gitlab.com`)
-to apply additional packs of CI minutes, for personal namespaces or top-level groups within GitLab.com.
-
-### Creating an additional pack
-
-Use a POST to create additional packs.
-
-```plaintext
-POST /namespaces/:id/minutes
-```
-
-| Attribute   | Type    | Required | Description |
-|:------------|:--------|:---------|:------------|
-| `packs`     | array   | yes      | An array of purchased minutes packs |
-| `packs[expires_at]` | date   | yes      | Expiry date of the purchased pack|
-| `packs[number_of_minutes]`  | integer    | yes       | Number of additional minutes |
-| `packs[purchase_xid]` | string  | yes       | The unique ID of the purchase |
-
-Example request:
-
-```shell
-curl --request POST \
-  --url "http://localhost:3000/api/v4/namespaces/123/minutes" \
-  --header 'Content-Type: application/json' \
-  --header 'PRIVATE-TOKEN: <admin access token>' \
-  --data '{
-    "packs": [
-      {
-        "number_of_minutes": 10000,
-        "expires_at": "2022-01-01",
-        "purchase_xid": "46952fe69bebc1a4de10b2b4ff439d0c"
-      }
-    ]
-  }'
-```
-
-Example response:
-
-```json
-[
-  {
-    "namespace_id": 123,
-    "expires_at": "2022-01-01",
-    "number_of_minutes": 10000,
-    "purchase_xid": "46952fe69bebc1a4de10b2b4ff439d0c"
-  }
-]
-```
-
-### Moving additional packs
-
-Use a PATCH to move additional packs from one namespace to another.
-
-```plaintext
-PATCH /namespaces/:id/minutes/move/:target_id
-```
-
-| Attribute   | Type    | Required | Description |
-|:------------|:--------|:---------|:------------|
-| `id` | string | yes | The ID of the namespace to transfer packs from |
-| `target_id`  | string | yes | The ID of the target namespace to transfer the packs to |
-
-Example request:
-
-```shell
-curl --request PATCH \
-  --url "http://localhost:3000/api/v4/namespaces/123/minutes/move/321" \
-  --header 'PRIVATE-TOKEN: <admin access token>'
-```
-
-Example response:
-
-```json
-{
-  "message": "202 Accepted"
-}
-```
-
-### Known consumers
-
-- CustomersDot
-
-## Upcoming reconciliations
-
-The `upcoming_reconciliations` endpoint is used by [CustomersDot](https://gitlab.com/gitlab-org/customers-gitlab-com) (`customers.gitlab.com`)
-to update upcoming reconciliations for namespaces.
-
-### Updating `upcoming_reconciliations`
-
-Use a PUT command to update `upcoming_reconciliations`.
-
-```plaintext
-PUT /internal/upcoming_reconciliations
-```
-
-| Attribute          | Type       | Required | Description |
-|:-------------------|:-----------|:---------|:------------|
-| `upcoming_reconciliations` | array | yes | Array of upcoming reconciliations |
-
-Each array element contains:
-
-| Attribute          | Type       | Required | Description |
-|:-------------------|:-----------|:---------|:------------|
-| `namespace_id`          | integer | yes | ID of the namespace to be reconciled |
-| `next_reconciliation_date` | date | yes | Date when next reconciliation will happen |
-| `display_alert_from`       | date | yes | Start date to display alert of upcoming reconciliation |
-
-Example request:
-
-```shell
-curl --request PUT --header "PRIVATE-TOKEN: <admin_access_token>" --header "Content-Type: application/json" \
-     --data '{"upcoming_reconciliations": [{"namespace_id": 127, "next_reconciliation_date": "13 Jun 2021", "display_alert_from": "06 Jun 2021"}, {"namespace_id": 129, "next_reconciliation_date": "12 Jun 2021", "display_alert_from": "05 Jun 2021"}]}' \
-     "https://gitlab.com/api/v4/internal/upcoming_reconciliations"
-```
-
-Example response:
-
-```plaintext
-200
-```
-
-### Known consumers
-
-- CustomersDot
+<!-- This redirect file can be deleted after <YYYY-MM-DD>. -->
+<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
diff --git a/doc/development/internal_api/index.md b/doc/development/internal_api/index.md
new file mode 100644
index 00000000000..8f8c5a3d8b4
--- /dev/null
+++ b/doc/development/internal_api/index.md
@@ -0,0 +1,829 @@
+---
+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, api
+---
+
+# Internal API **(FREE)**
+
+The internal API is used by different GitLab components, it can not be
+used by other consumers. This documentation is intended for people
+working on the GitLab codebase.
+
+This documentation does not yet include the internal API used by
+GitLab Pages.
+
+## Adding new endpoints
+
+API endpoints should be externally accessible by default, with proper authentication and authorization.
+Before adding a new internal endpoint, consider if the API would potentially be
+useful to the wider GitLab community and can be made externally accessible.
+
+One reason we might favor internal API endpoints sometimes is when using such an endpoint requires
+internal data that external actors can not have. For example, in the internal Pages API we might use
+a secret token that identifies a request as internal or sign a request with a public key that is
+not available to a wider community.
+
+Another reason to separate something into an internal API is when request to such API endpoint
+should never go through an edge (public) load balancer. This way we can configure different rate
+limiting rules and policies around how the endpoint is being accessed, because we know that only
+internal requests can be made to that endpoint going through an internal load balancer.
+
+## Authentication
+
+These methods are all authenticated using a shared secret. This secret
+is stored in a file at the path configured in `config/gitlab.yml` by
+default this is in the root of the rails app named
+`.gitlab_shell_secret`
+
+To authenticate using that token, clients read the contents of that
+file, and include the token Base64 encoded in a `secret_token` parameter
+or in the `Gitlab-Shared-Secret` header.
+
+NOTE:
+The internal API used by GitLab Pages, and GitLab Kubernetes Agent Server (`kas`) uses JSON Web Token (JWT)
+authentication, which is different from GitLab Shell.
+
+## Git Authentication
+
+This is called by [Gitaly](https://gitlab.com/gitlab-org/gitaly) and
+[GitLab Shell](https://gitlab.com/gitlab-org/gitlab-shell) to check access to a
+repository.
+
+- **When called from GitLab Shell**: No changes are passed, and the internal
+  API replies with the information needed to pass the request on to Gitaly.
+- **When called from Gitaly in a `pre-receive` hook**: The changes are passed
+  and validated to determine if the push is allowed.
+
+Calls are limited to 50 seconds each.
+
+```plaintext
+POST /internal/allowed
+```
+
+| Attribute | Type   | Required | Description |
+|:----------|:-------|:---------|:------------|
+| `key_id`  | string | no       | ID of the SSH-key used to connect to GitLab Shell |
+| `username` | string | no      | Username from the certificate used to connect to GitLab Shell |
+| `project`  | string | no (if `gl_repository` is passed) | Path to the project |
+| `gl_repository`  | string | no (if `project` is passed) | Repository identifier, such as `project-7` |
+| `protocol` | string | yes     | SSH when called from GitLab Shell, HTTP or SSH when called from Gitaly |
+| `action`   | string | yes     | Git command being run (`git-upload-pack`, `git-receive-pack`, `git-upload-archive`) |
+| `changes`  | string | yes     | `<oldrev> <newrev> <refname>` when called from Gitaly, the magic string `_any` when called from GitLab Shell |
+| `check_ip` | string | no     | IP address from which call to GitLab Shell was made |
+
+Example request:
+
+```shell
+curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded token>" \
+     --data "key_id=11&project=gnuwget/wget2&action=git-upload-pack&protocol=ssh" \
+     "http://localhost:3001/api/v4/internal/allowed"
+```
+
+Example response:
+
+```json
+{
+  "status": true,
+  "gl_repository": "project-3",
+  "gl_project_path": "gnuwget/wget2",
+  "gl_id": "user-1",
+  "gl_username": "root",
+  "git_config_options": [],
+  "gitaly": {
+    "repository": {
+      "storage_name": "default",
+      "relative_path": "@hashed/4e/07/4e07408562bedb8b60ce05c1decfe3ad16b72230967de01f640b7e4729b49fce.git",
+      "git_object_directory": "",
+      "git_alternate_object_directories": [],
+      "gl_repository": "project-3",
+      "gl_project_path": "gnuwget/wget2"
+    },
+    "address": "unix:/Users/bvl/repos/gitlab/gitaly.socket",
+    "token": null
+  },
+  "gl_console_messages": []
+}
+```
+
+### Known consumers
+
+- Gitaly
+- GitLab Shell
+
+## LFS Authentication
+
+This is the endpoint that gets called from GitLab Shell to provide
+information for LFS clients when the repository is accessed over SSH.
+
+| Attribute | Type   | Required | Description |
+|:----------|:-------|:---------|:------------|
+| `key_id`  | string | no       | ID of the SSH-key used to connect to GitLab Shell |
+| `username`| string | no       | Username from the certificate used to connect to GitLab Shell |
+| `project` | string | no       | Path to the project |
+
+Example request:
+
+```shell
+curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded token>" \
+     --data "key_id=11&project=gnuwget/wget2" "http://localhost:3001/api/v4/internal/lfs_authenticate"
+```
+
+```json
+{
+  "username": "root",
+  "lfs_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7ImFjdG9yIjoicm9vdCJ9LCJqdGkiOiIyYWJhZDcxZC0xNDFlLTQ2NGUtOTZlMi1mODllYWRiMGVmZTYiLCJpYXQiOjE1NzAxMTc2NzYsIm5iZiI6MTU3MDExNzY3MSwiZXhwIjoxNTcwMTE5NDc2fQ.g7atlBw1QMY7QEBVPE0LZ8ZlKtaRzaMRmNn41r2YITM",
+  "repository_http_path": "http://localhost:3001/gnuwget/wget2.git",
+  "expires_in": 1800
+}
+```
+
+### Known consumers
+
+- GitLab Shell
+
+## Authorized Keys Check
+
+This endpoint is called by the GitLab Shell authorized keys
+check. Which is called by OpenSSH for [fast SSH key
+lookup](../../administration/operations/fast_ssh_key_lookup.md).
+
+| Attribute | Type   | Required | Description |
+|:----------|:-------|:---------|:------------|
+| `key`     | string | yes      | SSH key as passed by OpenSSH to GitLab Shell |
+
+```plaintext
+GET /internal/authorized_keys
+```
+
+Example request:
+
+```shell
+curl --request GET --header "Gitlab-Shared-Secret: <Base64 encoded secret>" "http://localhost:3001/api/v4/internal/authorized_keys?key=<key as passed by OpenSSH>"
+```
+
+Example response:
+
+```json
+{
+  "id": 11,
+  "title": "admin@example.com",
+  "key": "ssh-rsa ...",
+  "created_at": "2019-06-27T15:29:02.219Z"
+}
+```
+
+### Known consumers
+
+- GitLab Shell
+
+## Get user for user ID or key
+
+This endpoint is used when a user performs `ssh git@gitlab.com`. It
+discovers the user associated with an SSH key.
+
+| Attribute | Type   | Required | Description |
+|:----------|:-------|:---------|:------------|
+| `key_id` | integer | no | The ID of the SSH key used as found in the authorized-keys file or through the `/authorized_keys` check |
+| `username` | string | no | Username of the user being looked up, used by GitLab Shell when authenticating using a certificate |
+
+```plaintext
+GET /internal/discover
+```
+
+Example request:
+
+```shell
+curl --request GET --header "Gitlab-Shared-Secret: <Base64 encoded secret>" "http://localhost:3001/api/v4/internal/discover?key_id=7"
+```
+
+Example response:
+
+```json
+{
+  "id": 7,
+  "name": "Dede Eichmann",
+  "username": "rubi"
+}
+```
+
+### Known consumers
+
+- GitLab Shell
+
+## Instance information
+
+This gets some generic information about the instance. This is used
+by Geo nodes to get information about each other.
+
+```plaintext
+GET /internal/check
+```
+
+Example request:
+
+```shell
+curl --request GET --header "Gitlab-Shared-Secret: <Base64 encoded secret>" "http://localhost:3001/api/v4/internal/check"
+```
+
+Example response:
+
+```json
+{
+  "api_version": "v4",
+  "gitlab_version": "12.3.0-pre",
+  "gitlab_rev": "d69c988e6a6",
+  "redis": true
+}
+```
+
+### Known consumers
+
+- GitLab Geo
+- GitLab Shell's `bin/check`
+- Gitaly
+
+## Get new 2FA recovery codes using an SSH key
+
+This is called from GitLab Shell and allows users to get new 2FA
+recovery codes based on their SSH key.
+
+| Attribute | Type   | Required | Description |
+|:----------|:-------|:---------|:------------|
+| `key_id`  | integer | no | The ID of the SSH key used as found in the authorized-keys file or through the `/authorized_keys` check |
+| `user_id` | integer | no | **Deprecated** User_id for which to generate new recovery codes |
+
+```plaintext
+GET /internal/two_factor_recovery_codes
+```
+
+Example request:
+
+```shell
+curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" \
+     --data "key_id=7" "http://localhost:3001/api/v4/internal/two_factor_recovery_codes"
+```
+
+Example response:
+
+```json
+{
+  "success": true,
+  "recovery_codes": [
+    "d93ee7037944afd5",
+    "19d7b84862de93dd",
+    "1e8c52169195bf71",
+    "be50444dddb7ca84",
+    "26048c77d161d5b7",
+    "482d5c03d1628c47",
+    "d2c695e309ce7679",
+    "dfb4748afc4f12a7",
+    "0e5f53d1399d7979",
+    "af04d5622153b020"
+  ]
+}
+```
+
+### Known consumers
+
+- GitLab Shell
+
+## Get new personal access-token
+
+This is called from GitLab Shell and allows users to generate a new
+personal access token.
+
+| Attribute | Type   | Required | Description |
+|:----------|:-------|:---------|:------------|
+| `name` | string | yes | The name of the new token |
+| `scopes` | string array | yes | The authorization scopes for the new token, these must be valid token scopes |
+| `expires_at` | string | no | The expiry date for the new token |
+| `key_id`  | integer | no | The ID of the SSH key used as found in the authorized-keys file or through the `/authorized_keys` check |
+| `user_id` | integer | no | User ID for which to generate the new token |
+
+```plaintext
+POST /internal/personal_access_token
+```
+
+Example request:
+
+```shell
+curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" \
+     --data "user_id=29&name=mytokenname&scopes[]=read_user&scopes[]=read_repository&expires_at=2020-07-24" \
+     "http://localhost:3001/api/v4/internal/personal_access_token"
+```
+
+Example response:
+
+```json
+{
+  "success": true,
+  "token": "Hf_79B288hRv_3-TSD1R",
+  "scopes": ["read_user","read_repository"],
+  "expires_at": "2020-07-24"
+}
+```
+
+### Known consumers
+
+- GitLab Shell
+
+## Incrementing counter on pre-receive
+
+This is called from the Gitaly hooks increasing the reference counter
+for a push that might be accepted.
+
+| Attribute | Type   | Required | Description |
+|:----------|:-------|:---------|:------------|
+| `gl_repository` | string | yes | repository identifier for the repository receiving the push |
+
+```plaintext
+POST /internal/pre_receive
+```
+
+Example request:
+
+```shell
+curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" \
+     --data "gl_repository=project-7" "http://localhost:3001/api/v4/internal/pre_receive"
+```
+
+Example response:
+
+```json
+{
+  "reference_counter_increased": true
+}
+```
+
+## PostReceive
+
+Called from Gitaly after a receiving a push. This triggers the
+`PostReceive`-worker in Sidekiq, processes the passed push options and
+builds the response including messages that need to be displayed to
+the user.
+
+| Attribute | Type   | Required | Description |
+|:----------|:-------|:---------|:------------|
+| `identifier` | string | yes | `user-[id]` or `key-[id]` Identifying the user performing the push |
+| `gl_repository` | string | yes | identifier of the repository being pushed to |
+| `push_options` | string array | no | array of push options |
+| `changes` | string | no | refs to be updated in the push in the format `oldrev newrev refname\n`. |
+
+```plaintext
+POST /internal/post_receive
+```
+
+Example Request:
+
+```shell
+curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" \
+     --data "gl_repository=project-7" --data "identifier=user-1" \
+     --data "changes=0000000000000000000000000000000000000000 fd9e76b9136bdd9fe217061b497745792fe5a5ee gh-pages\n" \
+     "http://localhost:3001/api/v4/internal/post_receive"
+```
+
+Example response:
+
+```json
+{
+  "messages": [
+    {
+      "message": "Hello from post-receive",
+      "type": "alert"
+    }
+  ],
+  "reference_counter_decreased": true
+}
+```
+
+## Kubernetes agent endpoints
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41045) in GitLab 13.4.
+> - This feature is not deployed on GitLab.com
+> - It's not recommended for production use.
+
+The following endpoints are used by the GitLab Kubernetes Agent Server (`kas`)
+for various purposes.
+
+These endpoints are all authenticated using JWT. The JWT secret is stored in a file
+specified in `config/gitlab.yml`. By default, the location is in the root of the
+GitLab Rails app in a file called `.gitlab_kas_secret`.
+
+WARNING:
+The Kubernetes agent is under development and is not recommended for production use.
+
+### Kubernetes agent information
+
+Called from GitLab Kubernetes Agent Server (`kas`) to retrieve agent
+information for the given agent token. This returns the Gitaly connection
+information for the agent's project in order for `kas` to fetch and update
+the agent's configuration.
+
+```plaintext
+GET /internal/kubernetes/agent_info
+```
+
+Example Request:
+
+```shell
+curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \
+     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/agent_info"
+```
+
+### Kubernetes agent project information
+
+Called from GitLab Kubernetes Agent Server (`kas`) to retrieve project
+information for the given agent token. This returns the Gitaly
+connection for the requested project. GitLab `kas` uses this to configure
+the agent to fetch Kubernetes resources from the project repository to
+sync.
+
+Only public projects are supported. For private projects, the ability for the
+agent to be authorized is [not yet implemented](https://gitlab.com/gitlab-org/gitlab/-/issues/220912).
+
+| Attribute | Type   | Required | Description |
+|:----------|:-------|:---------|:------------|
+| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../api/index.md#namespaced-path-encoding) |
+
+```plaintext
+GET /internal/kubernetes/project_info
+```
+
+Example Request:
+
+```shell
+curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \
+     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/project_info?id=7"
+```
+
+### Kubernetes agent usage metrics
+
+Called from GitLab Kubernetes Agent Server (`kas`) to increase the usage
+metric counters.
+
+| Attribute | Type   | Required | Description |
+|:----------|:-------|:---------|:------------|
+| `gitops_sync_count` | integer| no | The number to increase the `gitops_sync_count` counter by |
+| `k8s_api_proxy_request_count` | integer| no | The number to increase the `k8s_api_proxy_request_count` counter by |
+
+```plaintext
+POST /internal/kubernetes/usage_metrics
+```
+
+Example Request:
+
+```shell
+curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" --header "Content-Type: application/json" \
+     --data '{"gitops_sync_count":1}' "http://localhost:3000/api/v4/internal/kubernetes/usage_metrics"
+```
+
+### Kubernetes agent alert metrics
+
+Called from GitLab Kubernetes Agent Server (KAS) to save alerts derived from Cilium on Kubernetes
+Cluster.
+
+| Attribute | Type   | Required | Description |
+|:----------|:-------|:---------|:------------|
+| `alert` | Hash | yes | Alerts detail. Same format as [3rd party alert](../../operations/incident_management/integrations.md#customize-the-alert-payload-outside-of-gitlab). |
+
+```plaintext
+POST internal/kubernetes/modules/cilium_alert
+```
+
+Example Request:
+
+```shell
+curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" \
+     --header "Authorization: Bearer <agent token>" --header "Content-Type: application/json" \
+     --data '"{\"alert\":{\"title\":\"minimal\",\"message\":\"network problem\",\"evalMatches\":[{\"value\":1,\"metric\":\"Count\",\"tags\":{}}]}}"' \
+     "http://localhost:3000/api/v4/internal/kubernetes/modules/cilium_alert"
+```
+
+### Create Starboard vulnerability
+
+Called from the GitLab Kubernetes Agent Server (`kas`) to create a security vulnerability
+from a Starboard vulnerability report. This request is idempotent. Multiple requests with the same data
+create a single vulnerability.
+
+| Attribute       | Type   | Required | Description |
+|:----------------|:-------|:---------|:------------|
+| `vulnerability` | Hash   | yes      | Vulnerability data matching the security report schema [`vulnerability` field](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/src/security-report-format.json). |
+| `scanner`       | Hash   | yes      | Scanner data matching the security report schema [`scanner` field](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/src/security-report-format.json). |
+
+```plaintext
+PUT internal/kubernetes/modules/starboard_vulnerability
+```
+
+Example Request:
+
+```shell
+curl --request PUT --header "Gitlab-Kas-Api-Request: <JWT token>" \
+     --header "Authorization: Bearer <agent token>" --header "Content-Type: application/json" \
+     --url "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability" \
+     --data '{
+  "vulnerability": {
+    "name": "CVE-123-4567 in libc",
+    "severity": "high",
+    "confidence": "unknown",
+    "location": {
+      "kubernetes_resource": {
+        "namespace": "production",
+        "kind": "deployment",
+        "name": "nginx",
+        "container": "nginx"
+      }
+    },
+    "identifiers": [
+      {
+        "type": "cve",
+        "name": "CVE-123-4567",
+        "value": "CVE-123-4567"
+      }
+    ]
+  },
+  "scanner": {
+    "id": "starboard_trivy",
+    "name": "Trivy (via Starboard Operator)",
+    "vendor": "GitLab"
+  }
+}'
+```
+
+## Subscriptions
+
+The subscriptions endpoint is used by [CustomersDot](https://gitlab.com/gitlab-org/customers-gitlab-com) (`customers.gitlab.com`)
+in order to apply subscriptions including trials, and add-on purchases, for personal namespaces or top-level groups within GitLab.com.
+
+### Creating a subscription
+
+Use a POST to create a subscription.
+
+```plaintext
+POST /namespaces/:id/gitlab_subscription
+```
+
+| Attribute   | Type    | Required | Description |
+|:------------|:--------|:---------|:------------|
+| `start_date` | date   | yes      | Start date of subscription |
+| `end_date`  | date    | no       | End date of subscription |
+| `plan_code` | string  | no       | Subscription tier code |
+| `seats`     | integer | no       | Number of seats in subscription |
+| `max_seats_used` | integer | no  | Highest number of active users in the last month |
+| `auto_renew` | boolean | no      | Whether subscription auto-renews on end date |
+| `trial`     | boolean | no       | Whether subscription is a trial |
+| `trial_starts_on` | date | no    | Start date of trial |
+| `trial_ends_on` | date | no      | End date of trial |
+
+Example request:
+
+```shell
+curl --request POST --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription?start_date="2020-07-15"&plan="premium"&seats=10"
+```
+
+Example response:
+
+```json
+{
+  "plan": {
+    "code":"premium",
+    "name":"premium",
+    "trial":false,
+    "auto_renew":null,
+    "upgradable":false
+  },
+  "usage": {
+    "seats_in_subscription":10,
+    "seats_in_use":1,
+    "max_seats_used":0,
+    "seats_owed":0
+  },
+  "billing": {
+    "subscription_start_date":"2020-07-15",
+    "subscription_end_date":null,
+    "trial_ends_on":null
+  }
+}
+```
+
+### Updating a subscription
+
+Use a PUT command to update an existing subscription.
+
+```plaintext
+PUT /namespaces/:id/gitlab_subscription
+```
+
+| Attribute   | Type    | Required | Description |
+|:------------|:--------|:---------|:------------|
+| `start_date` | date   | no       | Start date of subscription |
+| `end_date`  | date    | no       | End date of subscription |
+| `plan_code` | string  | no       | Subscription tier code |
+| `seats`     | integer | no       | Number of seats in subscription |
+| `max_seats_used` | integer | no  | Highest number of active users in the last month |
+| `auto_renew` | boolean | no      | Whether subscription auto-renews on end date |
+| `trial`     | boolean | no       | Whether subscription is a trial |
+| `trial_starts_on` | date | no    | Start date of trial. Required if trial is true. |
+| `trial_ends_on` | date | no      | End date of trial |
+
+Example request:
+
+```shell
+curl --request PUT --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription?max_seats_used=0"
+```
+
+Example response:
+
+```json
+{
+  "plan": {
+    "code":"premium",
+    "name":"premium",
+    "trial":false,
+    "auto_renew":null,
+    "upgradable":false
+  },
+  "usage": {
+    "seats_in_subscription":80,
+    "seats_in_use":82,
+    "max_seats_used":0,
+    "seats_owed":2
+  },
+  "billing": {
+    "subscription_start_date":"2020-07-15",
+    "subscription_end_date":"2021-07-15",
+    "trial_ends_on":null
+  }
+}
+```
+
+### Retrieving a subscription
+
+Use a GET command to view an existing subscription.
+
+```plaintext
+GET /namespaces/:id/gitlab_subscription
+```
+
+Example request:
+
+```shell
+curl --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription"
+```
+
+Example response:
+
+```json
+{
+  "plan": {
+    "code":"premium",
+    "name":"premium",
+    "trial":false,
+    "auto_renew":null,
+    "upgradable":false
+  },
+  "usage": {
+    "seats_in_subscription":80,
+    "seats_in_use":82,
+    "max_seats_used":82,
+    "seats_owed":2
+  },
+  "billing": {
+    "subscription_start_date":"2020-07-15",
+    "subscription_end_date":"2021-07-15",
+    "trial_ends_on":null
+  }
+}
+```
+
+### Known consumers
+
+- CustomersDot
+
+## CI minute provisioning
+
+The CI Minute endpoints are used by [CustomersDot](https://gitlab.com/gitlab-org/customers-gitlab-com) (`customers.gitlab.com`)
+to apply additional packs of CI minutes, for personal namespaces or top-level groups within GitLab.com.
+
+### Creating an additional pack
+
+Use a POST to create additional packs.
+
+```plaintext
+POST /namespaces/:id/minutes
+```
+
+| Attribute   | Type    | Required | Description |
+|:------------|:--------|:---------|:------------|
+| `packs`     | array   | yes      | An array of purchased minutes packs |
+| `packs[expires_at]` | date   | yes      | Expiry date of the purchased pack|
+| `packs[number_of_minutes]`  | integer    | yes       | Number of additional minutes |
+| `packs[purchase_xid]` | string  | yes       | The unique ID of the purchase |
+
+Example request:
+
+```shell
+curl --request POST \
+  --url "http://localhost:3000/api/v4/namespaces/123/minutes" \
+  --header 'Content-Type: application/json' \
+  --header 'PRIVATE-TOKEN: <admin access token>' \
+  --data '{
+    "packs": [
+      {
+        "number_of_minutes": 10000,
+        "expires_at": "2022-01-01",
+        "purchase_xid": "46952fe69bebc1a4de10b2b4ff439d0c"
+      }
+    ]
+  }'
+```
+
+Example response:
+
+```json
+[
+  {
+    "namespace_id": 123,
+    "expires_at": "2022-01-01",
+    "number_of_minutes": 10000,
+    "purchase_xid": "46952fe69bebc1a4de10b2b4ff439d0c"
+  }
+]
+```
+
+### Moving additional packs
+
+Use a PATCH to move additional packs from one namespace to another.
+
+```plaintext
+PATCH /namespaces/:id/minutes/move/:target_id
+```
+
+| Attribute   | Type    | Required | Description |
+|:------------|:--------|:---------|:------------|
+| `id` | string | yes | The ID of the namespace to transfer packs from |
+| `target_id`  | string | yes | The ID of the target namespace to transfer the packs to |
+
+Example request:
+
+```shell
+curl --request PATCH \
+  --url "http://localhost:3000/api/v4/namespaces/123/minutes/move/321" \
+  --header 'PRIVATE-TOKEN: <admin access token>'
+```
+
+Example response:
+
+```json
+{
+  "message": "202 Accepted"
+}
+```
+
+### Known consumers
+
+- CustomersDot
+
+## Upcoming reconciliations
+
+The `upcoming_reconciliations` endpoint is used by [CustomersDot](https://gitlab.com/gitlab-org/customers-gitlab-com) (`customers.gitlab.com`)
+to update upcoming reconciliations for namespaces.
+
+### Updating `upcoming_reconciliations`
+
+Use a PUT command to update `upcoming_reconciliations`.
+
+```plaintext
+PUT /internal/upcoming_reconciliations
+```
+
+| Attribute          | Type       | Required | Description |
+|:-------------------|:-----------|:---------|:------------|
+| `upcoming_reconciliations` | array | yes | Array of upcoming reconciliations |
+
+Each array element contains:
+
+| Attribute          | Type       | Required | Description |
+|:-------------------|:-----------|:---------|:------------|
+| `namespace_id`          | integer | yes | ID of the namespace to be reconciled |
+| `next_reconciliation_date` | date | yes | Date when next reconciliation will happen |
+| `display_alert_from`       | date | yes | Start date to display alert of upcoming reconciliation |
+
+Example request:
+
+```shell
+curl --request PUT --header "PRIVATE-TOKEN: <admin_access_token>" --header "Content-Type: application/json" \
+     --data '{"upcoming_reconciliations": [{"namespace_id": 127, "next_reconciliation_date": "13 Jun 2021", "display_alert_from": "06 Jun 2021"}, {"namespace_id": 129, "next_reconciliation_date": "12 Jun 2021", "display_alert_from": "05 Jun 2021"}]}' \
+     "https://gitlab.com/api/v4/internal/upcoming_reconciliations"
+```
+
+Example response:
+
+```plaintext
+200
+```
+
+### Known consumers
+
+- CustomersDot
diff --git a/doc/development/maintenance_mode.md b/doc/development/maintenance_mode.md
index e308ab26c27..c2fd4bab605 100644
--- a/doc/development/maintenance_mode.md
+++ b/doc/development/maintenance_mode.md
@@ -13,7 +13,7 @@ GitLab Maintenance Mode **only** blocks writes from HTTP and SSH requests at the
 
 - [the read-only database method](https://gitlab.com/gitlab-org/gitlab/-/blob/2425e9de50c678413ceaad6ee3bf66f42b7e228c/ee/lib/ee/gitlab/database.rb#L13), which toggles special behavior when we are not allowed to write to the database. [Search the codebase for `Gitlab::Database.read_only?`.](https://gitlab.com/search?search=Gitlab%3A%3ADatabase.read_only%3F&group_id=9970&project_id=278964&scope=blobs&search_code=false&snippets=false&repository_ref=)
 - [the read-only middleware](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/ee/gitlab/middleware/read_only/controller.rb), where HTTP requests that cause database writes are blocked, unless explicitly allowed.
-- [Git push access via SSH is denied](https://gitlab.com/gitlab-org/gitlab/-/blob/2425e9de50c678413ceaad6ee3bf66f42b7e228c/ee/lib/ee/gitlab/git_access.rb#L13) by returning 401 when `gitlab-shell` POSTs to [`/internal/allowed`](internal_api.md) to [check if access is allowed](internal_api.md#git-authentication).
+- [Git push access via SSH is denied](https://gitlab.com/gitlab-org/gitlab/-/blob/2425e9de50c678413ceaad6ee3bf66f42b7e228c/ee/lib/ee/gitlab/git_access.rb#L13) by returning 401 when `gitlab-shell` POSTs to [`/internal/allowed`](internal_api/index.md) to [check if access is allowed](internal_api/index.md#git-authentication).
 - [Container registry authentication service](https://gitlab.com/gitlab-org/gitlab/-/blob/2425e9de50c678413ceaad6ee3bf66f42b7e228c/ee/app/services/ee/auth/container_registry_authentication_service.rb#L12), where updates to the container registry are blocked.
 
 The database itself is not in read-only mode (except in a Geo secondary site) and can be written by sources other than the ones blocked.
diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md
index 870da6cdb3d..e243e1defe8 100644
--- a/doc/integration/auth0.md
+++ b/doc/integration/auth0.md
@@ -48,7 +48,7 @@ application.
    sudo -u git -H editor config/gitlab.yml
    ```
 
-1. Read [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration)
+1. Read [Configure initial settings](omniauth.md#configure-initial-settings)
    for initial settings.
 
 1. Add the provider configuration:
diff --git a/doc/integration/azure.md b/doc/integration/azure.md
index 3eb0344edda..c90ba70b703 100644
--- a/doc/integration/azure.md
+++ b/doc/integration/azure.md
@@ -48,7 +48,7 @@ As you go through the Microsoft procedure, keep the following in mind:
    sudo -u git -H editor config/gitlab.yml
    ```
 
-1. Refer to [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration)
+1. Refer to [Configure initial settings](omniauth.md#configure-initial-settings)
    for initial settings.
 
 1. Add the provider configuration:
@@ -154,7 +154,7 @@ After you have created an application, follow the [Microsoft Quickstart document
    sudo -u git -H editor config/gitlab.yml
    ```
 
-1. Refer to [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration)
+1. Refer to [Configure initial settings](omniauth.md#configure-initial-settings)
    for initial settings.
 
 1. Add the provider configuration:
diff --git a/doc/integration/cas.md b/doc/integration/cas.md
index 471b1e4e262..4699f7147aa 100644
--- a/doc/integration/cas.md
+++ b/doc/integration/cas.md
@@ -28,7 +28,7 @@ configure CAS for back-channel logout.
    sudo -u git -H editor config/gitlab.yml
    ```
 
-1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
+1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings.
 
 1. Add the provider configuration:
 
diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md
index 58c53db7996..1a3360aa470 100644
--- a/doc/integration/facebook.md
+++ b/doc/integration/facebook.md
@@ -72,7 +72,7 @@ Facebook. Facebook generates an app ID and secret key for you to use.
    sudo -u git -H editor config/gitlab.yml
    ```
 
-1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
+1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings.
 
 1. Add the provider configuration:
 
diff --git a/doc/integration/github.md b/doc/integration/github.md
index 16241c9293b..11a9a5ea64d 100644
--- a/doc/integration/github.md
+++ b/doc/integration/github.md
@@ -29,7 +29,7 @@ When you create an OAuth 2 app in GitHub, you need the following information:
 - The URL of your GitLab instance, such as `https://gitlab.example.com`.
 - The authorization callback URL; in this case, `https://gitlab.example.com/users/auth`. Include the port number if your GitLab instance uses a non-default port.
 
-See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
+See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings.
 
 After you have configured the GitHub provider, you need the following information. You must substitute that information in the GitLab configuration file in these next steps.
 
diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md
index 5e28765bb86..b69147b3829 100644
--- a/doc/integration/gitlab.md
+++ b/doc/integration/gitlab.md
@@ -45,7 +45,7 @@ GitLab.com generates an application ID and secret key for you to use.
    sudo -u git -H editor config/gitlab.yml
    ```
 
-1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
+1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings.
 1. Add the provider configuration:
 
    For Omnibus installations authenticating against **GitLab.com**:
diff --git a/doc/integration/google.md b/doc/integration/google.md
index 172015f7528..5df76ebb3d1 100644
--- a/doc/integration/google.md
+++ b/doc/integration/google.md
@@ -71,7 +71,7 @@ On your GitLab server:
    sudo -u git -H editor config/gitlab.yml
    ```
 
-1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
+1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings.
 1. Add the provider configuration:
 
    For Omnibus GitLab:
diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md
index 2d4abb75875..0f9bf3ba1d1 100644
--- a/doc/integration/kerberos.md
+++ b/doc/integration/kerberos.md
@@ -100,7 +100,7 @@ to authenticate with Kerberos tokens.
 
 #### Enable single sign-on
 
-See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration)
+See [Configure initial settings](omniauth.md#configure-initial-settings)
 for initial settings to enable single sign-on and add Kerberos servers
 as an identity provider.
 
@@ -137,7 +137,7 @@ with your Kerberos credentials.
 
 The first time users sign in to GitLab with their Kerberos accounts,
 GitLab creates a matching account.
-Before you continue, review the [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) options in Omnibus and GitLab source. You must also include `kerberos`.
+Before you continue, review the [Configure initial settings](omniauth.md#configure-initial-settings) options in Omnibus and GitLab source. You must also include `kerberos`.
 
 With that information at hand:
 
diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md
index bdf6a0e687d..8eb6d86b9b8 100644
--- a/doc/integration/oauth2_generic.md
+++ b/doc/integration/oauth2_generic.md
@@ -55,7 +55,7 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc
    sudo -u git -H editor config/gitlab.yml
    ```
 
-1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings
+1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings
 
 1. Add the provider-specific configuration for your provider, as [described in the gem's README](https://gitlab.com/satorix/omniauth-oauth2-generic#gitlab-config-example)
 
diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md
index 6c154ee7f5b..0beb95df82e 100644
--- a/doc/integration/omniauth.md
+++ b/doc/integration/omniauth.md
@@ -6,25 +6,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # OmniAuth **(FREE SELF)**
 
-GitLab leverages OmniAuth to allow users to sign in using Twitter, GitHub, and
-other popular services. [OmniAuth](https://rubygems.org/gems/omniauth/) is a
-"generalized Rack framework for multiple-provider authentication" built on Ruby.
+Users can sign in to GitLab by using their credentials from Twitter, GitHub, and other popular services.
+[OmniAuth](https://rubygems.org/gems/omniauth/) is the Rack
+framework that GitLab uses to provide this authentication.
 
-Configuring OmniAuth does not prevent standard GitLab authentication or LDAP
-(if configured) from continuing to work. Users can choose to sign in using any
-of the configured mechanisms.
+If you configure OmniAuth, users can continue to sign in using other
+mechanisms, including standard GitLab authentication or LDAP (if configured).
 
-- [Initial OmniAuth Configuration](#initial-omniauth-configuration)
-- [Supported Providers](#supported-providers)
-- [Enable OmniAuth for an Existing User](#enable-omniauth-for-an-existing-user)
-- [OmniAuth configuration sample when using Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master#omniauth-google-twitter-github-login)
-- [Enable or disable Sign In with an OmniAuth provider without disabling import sources](#enable-or-disable-sign-in-with-an-omniauth-provider-without-disabling-import-sources)
+## Supported providers
 
-## Supported Providers
-
-This is a list of the current supported OmniAuth providers. Before proceeding on
-each provider's documentation, make sure to first read this document as it
-contains some settings that are common for all providers.
+GitLab supports the following OmniAuth providers.
 
 | Provider documentation                                              | OmniAuth provider name     |
 |---------------------------------------------------------------------|----------------------------|
@@ -50,100 +41,78 @@ contains some settings that are common for all providers.
 | [Shibboleth](saml.md)                                         | `shibboleth`               |
 | [Twitter](twitter.md)                                               | `twitter`                  |
 
-## Initial OmniAuth Configuration
-
-The OmniAuth provider names from the table above are needed to configure a few
-global settings that are in common for all providers.
+## Configure initial settings
 
 NOTE:
-Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an
+In GitLab 11.4 and later, OmniAuth is enabled by default. If you're using an
 earlier version, you must explicitly enable it.
 
-- `allow_single_sign_on` allows you to specify the providers that automatically
-  create a GitLab account. For example, if you wish to enable Azure (v2) and Google,
-  in Omnibus, specify a list of provider names:
+Before you configure the OmniAuth provider,
+configure the settings that are common for all providers.
 
-  ```ruby
-  gitlab_rails['omniauth_allow_single_sign_on'] = ['azure_activedirectory_v2', 'google_oauth2']
-  ```
-
-  The value defaults to `false`. If `false` users must be created manually, or
-  they can't sign in by using OmniAuth.
-
-- `auto_link_ldap_user` can be used if you have [LDAP / ActiveDirectory](../administration/auth/ldap/index.md)
-  integration enabled. It defaults to `false`. When enabled, users automatically
-  created through an OmniAuth provider have their LDAP identity created in GitLab as well.
-- `block_auto_created_users` defaults to `true`. If `true`, auto created users will
-  be blocked pending approval by an administrator before they are able to sign in.
-
-NOTE:
-If you set `block_auto_created_users` to `false`, make sure to only
-define providers under `allow_single_sign_on` that you are able to control, like
-SAML, Shibboleth, Crowd, or Google. Otherwise, set it to `true`, or any user on
-the Internet can successfully sign in to your GitLab without
-administrative approval.
-
-NOTE:
-`auto_link_ldap_user` requires the `uid` of the user to be the same in both LDAP
-and the OmniAuth provider.
+Setting                    | Description | Default value
+---------------------------|-------------|--------------
+`allow_single_sign_on`     | Enables you to list the providers that automatically create a GitLab account. The provider names are available in the **OmniAuth provider name** column in the [supported providers table](#supported-providers). | The default is `false`. If `false`, users must be created manually, or they can't sign in using OmniAuth.
+`auto_link_ldap_user`      | If enabled, creates an LDAP identity in GitLab for users that are created through an OmniAuth provider. You can enable this setting if you have the [LDAP (ActiveDirectory)](../administration/auth/ldap/index.md) integration enabled. Requires the `uid` of the user to be the same in both LDAP and the OmniAuth provider. | The default is `false`.
+`block_auto_created_users` | If enabled, blocks users that are automatically created from signing in until they are approved by an administrator. | The default is `true`. If you set the value to `false`, make sure you only define providers for `allow_single_sign_on` that you can control, like SAML, Shibboleth, Crowd, or Google. Otherwise, any user on the internet can sign in to GitLab without an administrator's approval.
 
 To change these settings:
 
 - **For Omnibus package**
 
-  Open the configuration file:
+  1. Open the configuration file:
 
-  ```shell
-  sudo editor /etc/gitlab/gitlab.rb
-  ```
+     ```shell
+     sudo editor /etc/gitlab/gitlab.rb
+     ```
 
-  and change:
+  1. Update the following section:
 
-  ```ruby
-  # CAUTION!
-  # This allows users to sign in without having a user account first. Define the allowed providers
-  # using an array, for example, ["saml", "twitter"], or as true/false to allow all providers or none.
-  # User accounts will be created automatically when authentication was successful.
-  gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'twitter']
-  gitlab_rails['omniauth_auto_link_ldap_user'] = true
-  gitlab_rails['omniauth_block_auto_created_users'] = true
-  ```
+     ```ruby
+     # CAUTION!
+     # This allows users to sign in without having a user account first. Define the allowed providers
+     # using an array, for example, ["saml", "twitter"], or as true/false to allow all providers or none.
+     # User accounts will be created automatically when authentication was successful.
+     gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'twitter']
+     gitlab_rails['omniauth_auto_link_ldap_user'] = true
+     gitlab_rails['omniauth_block_auto_created_users'] = true
+     ```
 
 - **For installations from source**
 
-  Open the configuration file:
+  1. Open the configuration file:
 
-  ```shell
-  cd /home/git/gitlab
+     ```shell
+     cd /home/git/gitlab
 
-  sudo -u git -H editor config/gitlab.yml
-  ```
+     sudo -u git -H editor config/gitlab.yml
+     ```
 
-  and change the following section:
+  1. Update the following section:
 
-  ```yaml
-  ## OmniAuth settings
-  omniauth:
-    # Allow sign-in by using Twitter, Google, etc. using OmniAuth providers
-    # Versions prior to 11.4 require this to be set to true
-    # enabled: true
+     ```yaml
+     ## OmniAuth settings
+     omniauth:
+       # Allow sign-in by using Twitter, Google, etc. using OmniAuth providers
+       # Versions prior to 11.4 require this to be set to true
+       # enabled: true
 
-    # CAUTION!
-    # This allows users to sign in without having a user account first. Define the allowed providers
-    # using an array, for example, ["saml", "twitter"], or as true/false to allow all providers or none.
-    # User accounts will be created automatically when authentication was successful.
-    allow_single_sign_on: ["saml", "twitter"]
+       # CAUTION!
+       # This allows users to sign in without having a user account first. Define the allowed providers
+       # using an array, for example, ["saml", "twitter"], or as true/false to allow all providers or none.
+       # User accounts will be created automatically when authentication was successful.
+       allow_single_sign_on: ["saml", "twitter"]
 
-    auto_link_ldap_user: true
+       auto_link_ldap_user: true
 
-    # Locks down those users until they have been cleared by the admin (default: true).
-    block_auto_created_users: true
-  ```
+       # Locks down those users until they have been cleared by the admin (default: true).
+       block_auto_created_users: true
+     ```
 
-Now we can choose one or more of the [Supported Providers](#supported-providers)
-listed above to continue the configuration process.
+After configuring these settings, you can configure
+your chosen [provider](#supported-providers).
 
-## Enable OmniAuth for an Existing User
+## Enable OmniAuth for an existing user
 
 Existing users can enable OmniAuth for specific providers after the account is
 created. For example, if the user originally signed in with LDAP, an OmniAuth
@@ -160,7 +129,7 @@ OmniAuth provider for an existing user.
 
 The chosen OmniAuth provider is now active and can be used to sign in to GitLab from then on.
 
-## Automatically Link Existing Users to OmniAuth Users
+## Link existing users to OmniAuth users
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36664) in GitLab 13.4.
 
@@ -185,7 +154,7 @@ feature for both an **OpenID Connect provider** and a **Twitter OAuth provider**
     auto_link_user: ["openid_connect", "twitter"]
   ```
 
-## Configure OmniAuth Providers as External
+## Configure OmniAuth providers as external
 
 You can define which OmniAuth providers you want to be `external`. Users
 creating accounts, or logging in by using these `external` providers cannot have
@@ -211,7 +180,7 @@ their accounts to be upgraded to full internal accounts.
     external_providers: ['twitter', 'google_oauth2']
   ```
 
-## Using Custom OmniAuth Providers
+## Use a custom OmniAuth provider
 
 NOTE:
 The following information only applies for installations from source.
@@ -221,8 +190,6 @@ with a few providers pre-installed, such as LDAP, GitHub, and Twitter. You may a
 have to integrate with other authentication solutions. For
 these cases, you can use the OmniAuth provider.
 
-### Steps
-
 These steps are fairly general and you must figure out the exact details
 from the OmniAuth provider's documentation.
 
@@ -252,7 +219,7 @@ from the OmniAuth provider's documentation.
   sudo service gitlab start
   ```
 
-### Examples
+### Custom OmniAuth provider examples
 
 If you have successfully set up a provider that is not shipped with GitLab itself,
 please let us know.
@@ -260,7 +227,7 @@ please let us know.
 While we can't officially support every possible authentication mechanism out there,
 we'd like to at least help those with specific needs.
 
-## Enable or disable Sign In with an OmniAuth provider without disabling import sources
+## Enable or disable sign-in with an OmniAuth provider without disabling import sources
 
 Administrators are able to enable or disable **Sign In** by using some OmniAuth providers.
 
@@ -276,7 +243,7 @@ To enable/disable an OmniAuth provider:
 
    ![Enabled OAuth Sign-In sources](img/enabled-oauth-sign-in-sources_v13_10.png)
 
-## Disabling OmniAuth
+## Disable OmniAuth
 
 Starting from version 11.4 of GitLab, OmniAuth is enabled by default. This only
 has an effect if providers are configured and [enabled](#enable-or-disable-sign-in-with-an-omniauth-provider-without-disabling-import-sources).
@@ -318,7 +285,7 @@ When authenticating using LDAP, the user's name and email are always synced.
     sync_profile_attributes: ['email', 'location']
   ```
 
-## Bypassing two factor authentication
+## Bypass two-factor authentication
 
 In GitLab 12.3 or later, users can sign in with specified providers _without_
 using two factor authentication.
@@ -341,7 +308,7 @@ configured only for providers which already have two factor authentication
     allow_bypass_two_factor: ['twitter', 'google_oauth2']
   ```
 
-## Automatically sign in with provider
+## Sign in with a provider automatically
 
 You can add the `auto_sign_in_with_provider` setting to your GitLab
 configuration to redirect login requests to your OmniAuth provider for
diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md
index bc2ce738e2f..68daced3521 100644
--- a/doc/integration/salesforce.md
+++ b/doc/integration/salesforce.md
@@ -48,7 +48,7 @@ To get the credentials (a pair of Client ID and Client Secret), you must [create
    sudo -u git -H editor config/gitlab.yml
    ```
 
-1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
+1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings.
 
 1. Add the provider configuration:
 
diff --git a/doc/integration/saml.md b/doc/integration/saml.md
index a2955c4df48..47a35cf21a8 100644
--- a/doc/integration/saml.md
+++ b/doc/integration/saml.md
@@ -53,7 +53,7 @@ in your SAML IdP:
    sudo -u git -H editor config/gitlab.yml
    ```
 
-1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
+1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings.
 1. To allow your users to use SAML to sign up without having to manually create
    an account first, add the following values to your configuration:
 
diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md
index f8dd552ec6a..50ef04681f0 100644
--- a/doc/integration/twitter.md
+++ b/doc/integration/twitter.md
@@ -53,7 +53,7 @@ Twitter. Twitter generates a client ID and secret key for you to use.
      sudo -u git -H editor config/gitlab.yml
    ```
 
-1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
+1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings.
 
 1. Add the provider configuration:
 
diff --git a/doc/subscriptions/self_managed/index.md b/doc/subscriptions/self_managed/index.md
index 9650f043470..aee18e3d763 100644
--- a/doc/subscriptions/self_managed/index.md
+++ b/doc/subscriptions/self_managed/index.md
@@ -108,7 +108,7 @@ GitLab has several features which can help you manage the number of users:
 
 - Enable the [**Require administrator approval for new sign ups**](../../user/admin_area/settings/sign_up_restrictions.md#require-administrator-approval-for-new-sign-ups)
   option.
-- Enable `block_auto_created_users` for new sign-ups via [LDAP](../../administration/auth/ldap/index.md#basic-configuration-settings) or [OmniAuth](../../integration/omniauth.md#initial-omniauth-configuration).
+- Enable `block_auto_created_users` for new sign-ups via [LDAP](../../administration/auth/ldap/index.md#basic-configuration-settings) or [OmniAuth](../../integration/omniauth.md#configure-initial-settings).
 - Enable the [User cap](../../user/admin_area/settings/sign_up_restrictions.md#user-cap)
   option. **Available in GitLab 13.7 and later**.
 - [Disable new sign-ups](../../user/admin_area/settings/sign_up_restrictions.md), and instead manage new
diff --git a/doc/topics/git/git_rebase.md b/doc/topics/git/git_rebase.md
index 72bb2bf3fdc..c0bc7ed4e5c 100644
--- a/doc/topics/git/git_rebase.md
+++ b/doc/topics/git/git_rebase.md
@@ -145,6 +145,11 @@ To rebase from the UI:
 GitLab schedules a rebase of the feature branch against the default branch and
 executes it as soon as possible.
 
+The user performing the rebase action is considered
+a user that added commits to the merge request. When the merge request approvals setting
+[**Prevent approvals by users who add commits**](../../user/project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits)
+is enabled, this setting prevents the user from also approving the merge request.
+
 ### Interactive rebase
 
 You can use interactive rebase to modify commits. For example, amend a commit
diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md
index c8f160f729f..a98250dfc56 100644
--- a/doc/user/admin_area/moderate_users.md
+++ b/doc/user/admin_area/moderate_users.md
@@ -17,7 +17,7 @@ pending approval state because an administrator has enabled any of the following
 
 - [Require admin approval for new sign-ups](settings/sign_up_restrictions.md#require-administrator-approval-for-new-sign-ups) setting.
 - [User cap](settings/sign_up_restrictions.md#user-cap).
-- [Block auto-created users (OmniAuth)](../../integration/omniauth.md#initial-omniauth-configuration)
+- [Block auto-created users (OmniAuth)](../../integration/omniauth.md#configure-initial-settings)
 - [Block auto-created users (LDAP)](../../administration/auth/ldap/index.md#basic-configuration-settings)
 
 When a user registers for an account while this setting is enabled:
diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md
index ed80bca470e..8ce3b4f1c18 100644
--- a/doc/user/admin_area/settings/sign_up_restrictions.md
+++ b/doc/user/admin_area/settings/sign_up_restrictions.md
@@ -48,7 +48,7 @@ automatically approved in a background job.
 NOTE:
 This setting doesn't apply to LDAP or OmniAuth users. To enforce approvals for new users
 signing up using OmniAuth or LDAP, set `block_auto_created_users` to `true` in the
-[OmniAuth configuration](../../../integration/omniauth.md#initial-omniauth-configuration) or
+[OmniAuth configuration](../../../integration/omniauth.md#configure-initial-settings) or
 [LDAP configuration](../../../administration/auth/ldap/index.md#basic-configuration-settings).
 
 ## Require email confirmation
diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md
index 7bfaacd96a3..1332310b850 100644
--- a/doc/user/clusters/management_project.md
+++ b/doc/user/clusters/management_project.md
@@ -10,8 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
 
 WARNING:
-This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
-
+The cluster management project was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
 To manage cluster applications, use the [GitLab Kubernetes Agent](agent/index.md)
 with the [Cluster Management Project Template](management_project_template.md).
 
diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md
index 4f6140197ec..72fa9e1e310 100644
--- a/doc/user/group/epics/manage_epics.md
+++ b/doc/user/group/epics/manage_epics.md
@@ -25,10 +25,11 @@ To create an epic in the group you're in:
    - In an empty [roadmap](../roadmap/index.md), select **New epic**.
 
 1. Enter a title.
-1. Optional. Enter a description.
-1. Optional. To make the epic confidential, select the [Confidentiality checkbox](#make-an-epic-confidential).
-1. Optional. Choose labels.
-1. Optional. Select a start and due date, or [inherit](#start-and-due-date-inheritance) them.
+1. Complete the fields.
+   - Enter a description.
+   - To [make the epic confidential](#make-an-epic-confidential), select the checkbox under **Confidentiality**.
+   - Choose labels.
+   - Select a start and due date, or [inherit](#start-and-due-date-inheritance) them.
 1. Select **Create epic**.
 
 The newly created epic opens.
@@ -69,13 +70,13 @@ After you create an epic, you can edit the following details:
 
 To edit an epic's title or description:
 
-1. Select the **Edit title and description** **{pencil}** button.
+1. Select **Edit title and description** **{pencil}**.
 1. Make your changes.
 1. Select **Save changes**.
 
 To edit an epic's start date, due date, or labels:
 
-1. Select **Edit** next to each section in the epic sidebar.
+1. Next to each section in the right sidebar, select **Edit**.
 1. Select the dates or labels for your epic.
 
 ## Bulk edit epics
@@ -89,18 +90,21 @@ When bulk editing epics in a group, you can edit their labels.
 To update multiple epics at the same time:
 
 1. In a group, go to **Epics > List**.
-1. Click **Edit epics**. A sidebar on the right-hand side of your screen appears with editable fields.
-1. Check the checkboxes next to each epic you want to edit.
+1. Select **Edit epics**. A sidebar on the right appears with editable fields.
+1. Select the checkboxes next to each epic you want to edit.
 1. Select the appropriate fields and their values from the sidebar.
-1. Click **Update all**.
+1. Select **Update all**.
 
 ## Delete an epic
 
 NOTE:
-To delete an epic, you need to be an [Owner](../../permissions.md#group-members-permissions) of a group/subgroup.
+To delete an epic, you must be an [Owner](../../permissions.md#group-members-permissions) of a group
+or subgroup.
 
-When editing the description of an epic, select the **Delete** button to delete the epic.
-A modal appears to confirm your action.
+To delete the epic:
+
+1. Select **Edit title and description** **{pencil}**.
+1. Select **Delete**. A modal appears to confirm your action.
 
 Deleting an epic releases all existing issues from their associated epic in the system.
 
@@ -112,26 +116,26 @@ If you delete an epic, all its child epics and their descendants are deleted as
 Whenever you decide that there is no longer need for that epic,
 close the epic by:
 
-- Selecting the **Close epic** button.
+- Selecting **Close epic**.
 
   ![close epic - button](img/button_close_epic.png)
 
-- Using a [quick action](../../project/quick_actions.md).
+- Using the `/close` [quick action](../../project/quick_actions.md).
 
 ## Reopen a closed epic
 
 You can reopen an epic that was closed by:
 
-- Clicking the **Reopen epic** button.
+- Selecting **Reopen epic**.
 
   ![reopen epic - button](img/button_reopen_epic.png)
 
-- Using a [quick action](../../project/quick_actions.md).
+- Using the `/reopen` [quick action](../../project/quick_actions.md).
 
 ## Go to an epic from an issue
 
-If an issue belongs to an epic, you can navigate to the containing epic with the
-link in the issue sidebar.
+If an issue belongs to an epic, you can go to the parent epic with the
+link in the right sidebar.
 
 ![containing epic](img/containing_epic.png)
 
@@ -156,13 +160,12 @@ than 1000. The cached value is rounded to thousands or millions and updated ever
 
 ## Search for an epic from epics list page
 
-> - Introduced in GitLab 10.5.
 > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) from GitLab Ultimate to GitLab Premium in 12.8.
 > - Searching by the user's reaction emoji [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325630) in GitLab 13.11.
 > - Sorting by epic titles [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331625) in GitLab 14.1.
 
-You can search for an epic from the list of epics using filtered search bar (similar to
-that of issues and merge requests) based on following parameters:
+You can search for an epic from the list of epics using filtered search bar based on following
+parameters:
 
 - Title or description
 - Author name / username
@@ -171,10 +174,13 @@ that of issues and merge requests) based on following parameters:
 
 ![epics search](img/epics_search_v13_11.png)
 
-To search, go to the list of epics and select the field **Search or filter results**.
-It displays a dropdown menu, from which you can add an author. You can also enter plain
-text to search by epic title or description. When done, press <kbd>Enter</kbd> on your
-keyboard to filter the list.
+To search:
+
+1. On the top bar, select **Menu > Groups** and find your group.
+1. On the left sidebar, select **Epics**.
+1. Select the field **Search or filter results**.
+1. From the dropdown menu, select the scope or enter plain text to search by epic title or description.
+1. Press <kbd>Enter</kbd> on your keyboard. The list is filtered.
 
 You can also sort epics list by:
 
@@ -198,7 +204,7 @@ You can reverse the default order and interact with the activity feed sorted by
 at the top. Your preference is saved via local storage and automatically applied to every epic and issue
 you view.
 
-To change the activity sort order, click the **Oldest first** dropdown menu and select either oldest
+To change the activity sort order, select the **Oldest first** dropdown menu and select either oldest
 or newest items to be shown first.
 
 ![Issue activity sort order dropdown button](img/epic_activity_sort_order_v13_2.png)
@@ -219,8 +225,8 @@ to learn how to create a confidential merge request.
 
 To make an epic confidential:
 
-- **When creating an epic:** select the checkbox **Make this epic confidential**.
-- **In an existing epic:** in the epic's sidebar, select **Edit** next to **Confidentiality** then
+- **When creating an epic:** select the checkbox under **Confidentiality**.
+- **In an existing epic:** on the right sidebar, select **Edit** next to **Confidentiality**, and then
   select **Turn on**.
 
 ## Manage issues assigned to an epic
@@ -252,7 +258,7 @@ current parent.
 
 To add a new issue to an epic:
 
-1. On the epic's page, under **Epics and Issues**, select the **Add** dropdown button.
+1. On the epic's page, under **Epics and Issues**, select **Add**.
 1. Select **Add an existing issue**.
 1. Identify the issue to be added, using either of the following methods:
    - Paste the link of the issue.
@@ -271,7 +277,7 @@ while dividing work into smaller parts.
 
 To create an issue from an epic:
 
-1. On the epic's page, under **Epics and Issues**, select the **Add** dropdown button.
+1. On the epic's page, under **Epics and Issues**, select **Add**.
 1. Select **Add a new issue**.
 1. Under **Title**, enter the title for the new issue.
 1. From the **Project** dropdown, select the project in which the issue should be created.
@@ -284,7 +290,7 @@ After you remove an issue from an epic, the issue is no longer associated with t
 
 To remove an issue from an epic:
 
-1. Select the **Remove** (**{close}**) button next to the issue you want to remove.
+1. Next to the issue you want to remove, select **Remove** (**{close}**).
    The **Remove issue** warning appears.
 1. Select **Remove**.
 
@@ -350,8 +356,6 @@ For more on epic templates, see [Epic Templates - Repeatable sets of issues](htt
 
 ## Multi-level child epics **(ULTIMATE)**
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8333) in GitLab 11.7.
-
 You can add any epic that belongs to a group or subgroup of the parent epic's group.
 New child epics appear at the top of the list of epics in the **Epics and Issues** tab.
 
@@ -363,7 +367,7 @@ Epics can contain multiple nested child epics, up to a total of seven levels dee
 
 To add a child epic to an epic:
 
-1. Select the **Add** dropdown button.
+1. Select **Add**.
 1. Select **Add a new epic**.
 1. Identify the epic to be added, using either of the following methods:
    - Paste the link of the epic.
@@ -403,5 +407,6 @@ To reorder child epics assigned to an epic:
 
 To remove a child epic from a parent epic:
 
-1. Select the <kbd>x</kbd> button in the parent epic's list of epics.
-1. Select **Remove** in the **Remove epic** warning message.
+1. Select **Remove** (**{close}**) in the parent epic's list of epics.
+   The **Remove epic** warning appears.
+1. Select **Remove**.
diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md
index ac4c3580af3..df3029ce581 100644
--- a/doc/user/project/import/github.md
+++ b/doc/user/project/import/github.md
@@ -25,6 +25,7 @@ The following aspects of a project are imported:
 - Pull request "merged by" information (GitLab.com & 13.7+)
 - Regular issue and pull request comments
 - [Git Large File Storage (LFS) Objects](../../../topics/git/lfs/index.md)
+- Pull request comments replies in discussions ([GitLab.com & 14.5+](https://gitlab.com/gitlab-org/gitlab/-/issues/336596))
 
 References to pull requests and issues are preserved (GitLab.com & 8.7+), and
 each imported repository maintains visibility level unless that [visibility
diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md
index 7edc379399b..078f8048900 100644
--- a/doc/user/project/merge_requests/fast_forward_merge.md
+++ b/doc/user/project/merge_requests/fast_forward_merge.md
@@ -38,6 +38,8 @@ Now, when you visit the merge request page, you can accept it
 If a fast-forward merge is not possible but a conflict free rebase is possible,
 a rebase button is offered.
 
+The rebase action is also available as a [quick action command: `/rebase`](../../../topics/git/git_rebase.md#rebase-from-the-gitlab-ui).
+
 ![Fast forward merge request](img/ff_merge_rebase.png)
 
 If the target branch is ahead of the source branch and a conflict free rebase is
diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md
index ac1cd57fb99..7bfb8e52279 100644
--- a/doc/user/project/merge_requests/reviews/suggestions.md
+++ b/doc/user/project/merge_requests/reviews/suggestions.md
@@ -7,14 +7,13 @@ type: index, reference
 
 # Suggest changes **(FREE)**
 
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18008) in GitLab 11.6.
-> - Custom commit messages for suggestions was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9 behind a [feature flag](../../../feature_flags.md), disabled by default.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) custom commit messages for suggestions in GitLab 13.9 [with a flag](../../../../administration/feature_flags.md) named `suggestions_custom_commit`. Disabled by default.
 > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/297404) in GitLab 13.10.
 
 As a reviewer, you're able to suggest code changes with a Markdown syntax in merge request
 diff threads. Then, the merge request author (or other users with appropriate
-[permission](../../../permissions.md)) is able to apply these suggestions with a click,
-which generates a commit in the merge request authored by the user that suggested the changes.
+[permission](../../../permissions.md)) can apply these suggestions with a click.
+This action generates a commit in the merge request, authored by the user that suggested the changes.
 
 1. Choose a line of code to be changed, add a new comment, then select
    the **Insert suggestion** icon in the toolbar:
@@ -38,14 +37,15 @@ which generates a commit in the merge request authored by the user that suggeste
 
    ![Custom commit](img/custom_commit_v13_9.png)
 
-After the author applies a suggestion, it's marked with the **Applied** label,
-the thread is automatically resolved, and GitLab creates a new commit
-and pushes the suggested change directly into the codebase in the merge request's
-branch. The [Developer role](../../../permissions.md) is required to do so.
+After the author applies a suggestion:
 
-## Multi-line suggestions
+1. The suggestion is marked as **Applied**.
+1. The thread is resolved.
+1. GitLab creates a new commit with the changes.
+1. If the user has the [Developer role](../../../permissions.md), GitLab pushes
+   the suggested change directly into the codebase in the merge request's branch.
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10.
+## Multi-line suggestions
 
 Reviewers can also suggest changes to multiple lines with a single suggestion
 within merge request diff threads by adjusting the range offsets. The
@@ -67,9 +67,9 @@ suggestion.
 
 ## Code block nested in suggestions
 
-If you need to make a suggestion that involves a
-[fenced code block](../../../markdown.md#code-spans-and-blocks), wrap your suggestion in four backticks
-instead of the usual three.
+To add a suggestion that includes a
+[fenced code block](../../../markdown.md#code-spans-and-blocks), wrap your suggestion
+in four backticks instead of three:
 
 ![A comment editor with a suggestion with a fenced code block](img/suggestion_code_block_editor_v12_8.png)
 
@@ -95,14 +95,14 @@ You can also use following variables besides static text:
 
 | Variable               | Description | Output example |
 |------------------------|-------------|----------------|
-| `%{branch_name}`       | The name of the branch the suggestion(s) was(were) applied to. | `my-feature-branch` |
-| `%{files_count}`       | The number of file(s) to which suggestion(s) was(were) applied.| **2** |
-| `%{file_paths}`        | The path(s) of the file(s) suggestion(s) was(were) applied to. Paths are separated by commas.| `docs/index.md, docs/about.md` |
+| `%{branch_name}`       | The name of the branch to which suggestions were applied. | `my-feature-branch` |
+| `%{files_count}`       | The number of files to which suggestions were applied.| **2** |
+| `%{file_paths}`        | The paths of the file to which suggestions were applied. Paths are separated by commas.| `docs/index.md, docs/about.md` |
 | `%{project_path}`      | The project path. | `my-group/my-project` |
 | `%{project_name}`      | The human-readable name of the project. | **My Project** |
 | `%{suggestions_count}` | The number of suggestions applied.| **3** |
-| `%{username}`          | The username of the user applying suggestion(s). | `user_1` |
-| `%{user_full_name}`    | The full name of the user applying suggestion(s). | **User 1** |
+| `%{username}`          | The username of the user applying suggestions. | `user_1` |
+| `%{user_full_name}`    | The full name of the user applying suggestions. | **User 1** |
 
 For example, to customize the commit message to output
 **Addresses user_1's review**, set the custom text to
@@ -114,32 +114,32 @@ introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/-/issues/25381).
 
 ## Batch suggestions
 
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha) behind a feature flag, disabled by default.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha) with a flag named `batch_suggestions`, disabled by default.
 > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) in GitLab 13.2.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11.
-> - Custom commit messages for batch suggestions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326168) in GitLab 14.4.
+> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11. [Feature flag `batch_suggestions`](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) removed.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326168) custom commit messages for batch suggestions in GitLab 14.4.
 
 You can apply multiple suggestions at once to reduce the number of commits added
 to your branch to address your reviewers' requests.
 
 1. To start a batch of suggestions to apply with a single commit, select **Add suggestion to batch**:
 
-   ![A code change suggestion displayed, with the button to add the suggestion to a batch highlighted.](img/add_first_suggestion_to_batch_v13_1.jpg "Add a suggestion to a batch")
+   ![A code change suggestion displayed, with the add-suggestion option highlighted.](img/add_first_suggestion_to_batch_v13_1.jpg "Add a suggestion to a batch")
 
 1. Add as many additional suggestions to the batch as you wish:
 
-   ![A code change suggestion displayed, with the button to add an additional suggestion to a batch highlighted.](img/add_another_suggestion_to_batch_v13_1.jpg "Add another suggestion to a batch")
+   ![A code change suggestion displayed, with the add-more suggestion option highlighted.](img/add_another_suggestion_to_batch_v13_1.jpg "Add another suggestion to a batch")
 
 1. To remove suggestions, select **Remove from batch**:
 
-   ![A code change suggestion displayed, with the button to remove that suggestion from its batch highlighted.](img/remove_suggestion_from_batch_v13_1.jpg "Remove a suggestion from a batch")
+   ![A code change suggestion displayed, with the option to remove that suggestion from its batch highlighted.](img/remove_suggestion_from_batch_v13_1.jpg "Remove a suggestion from a batch")
 
 1. Having added all the suggestions to your liking, when ready, select **Apply suggestions**. You
    can optionally specify a custom commit message for [batch suggestions](#batch-suggestions)
    (GitLab 14.4 and later) to describe your change. If you don't specify it, the default commit
    message is used.
 
-   ![A code change suggestion displayed, with the button to apply the batch of suggestions highlighted.](img/apply_batch_of_suggestions_v13_1.jpg "Apply a batch of suggestions")
+   ![A code change suggestion displayed, with the option to apply the batch of suggestions highlighted.](img/apply_batch_of_suggestions_v13_1.jpg "Apply a batch of suggestions")
 
 WARNING:
 Suggestions applied from multiple authors creates a commit authored by the user applying the suggestions.
diff --git a/doc/user/project/settings/img/general_settings_v13_11.png b/doc/user/project/settings/img/general_settings_v13_11.png
deleted file mode 100644
index 9da5acdf82e..00000000000
--- a/doc/user/project/settings/img/general_settings_v13_11.png
+++ /dev/null
diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md
index 30def6ae80f..1eba4fdcdb1 100644
--- a/doc/user/project/settings/index.md
+++ b/doc/user/project/settings/index.md
@@ -28,12 +28,29 @@ functionality of a project.
 
 Adjust your project's name, description, avatar, [default branch](../repository/branches/default.md), and topics:
 
-![general project settings](img/general_settings_v13_11.png)
-
 The project description also partially supports [standard Markdown](../../markdown.md#features-extended-from-standard-markdown).
 You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#links), and
 [line-breaks](../../markdown.md#line-breaks) to add more context to the project description.
 
+#### Topics
+
+Use topics to categorize projects and find similar new projects.
+
+To assign topics to a project:
+
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **Settings** > **General**.
+1. Under **Topics**, enter the project topics. Existing popular topics are suggested as you type.
+1. Select **Save changes**.
+
+For GitLab.com, explore popular topics on the [Explore topics page](https://gitlab.com/explore/projects/topics).
+When you select a topic, you can see relevant projects.
+
+NOTE:
+The assigned topics are visible only to everyone with access to the project,
+but everyone can see which topics exist at all on the GitLab instance.
+Do not include sensitive information in the name of a topic.
+
 #### Compliance frameworks **(PREMIUM)**
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276221) in GitLab 13.9.