Add latest changes from gitlab-org/gitlab@master

9 files changed, 233 insertions, 102 deletions

diff --git a/doc/administration/audit_event_streaming.md b/doc/administration/audit_event_streaming.md
index 0af1af12a60..0c65f888722 100644
--- a/doc/administration/audit_event_streaming.md
+++ b/doc/administration/audit_event_streaming.md
@@ -18,6 +18,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 > - Custom HTTP headers UI [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/365259) in GitLab 15.3. [Feature flag `custom_headers_streaming_audit_events_ui`](https://gitlab.com/gitlab-org/gitlab/-/issues/365259) removed.
 > - [Improved user experience](https://gitlab.com/gitlab-org/gitlab/-/issues/367963) in GitLab 15.3.
 > - User-specified verification token API support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360813) in GitLab 15.4.
+> - Event type filters API [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344845) in GitLab 15.7 [with a flag](feature_flags.md) named `allow_audit_event_type_filtering`. Disabled by default.
 
 Users can set a streaming destination for a top-level group to receive all audit events about the group, its subgroups, and
 projects as structured JSON.
@@ -143,6 +144,7 @@ query {
             id
           }
         }
+        eventTypeFilters
       }
     }
   }
@@ -284,6 +286,65 @@ Users with the Owner role for a group can list streaming destinations and see th
 1. On the main area, select the **Streams**.
 1. View the verification token on the right side of each item.
 
+## Event type filters
+
+> Event type filters API [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344845) in GitLab 15.7 [with a flag](feature_flags.md) named `allow_audit_event_type_filtering`. Disabled by default
+
+FLAG:
+On self-managed GitLab, by default this feature is not available. To make it available per group or for your entire instance, ask an administrator to
+[enable the feature flag](feature_flags.md) named `allow_audit_event_type_filtering`.
+
+When this feature is enabled for a group, you can use an API to permit users to filter streamed audit events per destination.
+If the feature is enabled with no filters, the destination receives all audit events.
+
+### Use the API to add an event type filter
+
+Prerequisites:
+
+- You must have the Owner role for the group.
+
+You can add a list of event type filters using the `auditEventsStreamingDestinationEventsAdd` query type:
+
+```graphql
+mutation {
+    auditEventsStreamingDestinationEventsAdd(input: {
+        destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/1",
+        eventTypeFilters: ["list of event type filters"]}){
+        errors
+        eventTypeFilters
+    }
+}
+```
+
+Event type filters are added if:
+
+- The returned `errors` object is empty.
+- The API responds with `200 OK`.
+
+### Use the API to remove an event type filter
+
+Prerequisites:
+
+- You must have the Owner role for the group.
+
+You can remove a list of event type filters using the `auditEventsStreamingDestinationEventsRemove` query type:
+
+```graphql
+mutation {
+    auditEventsStreamingDestinationEventsRemove(input: {
+    destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/1",
+    eventTypeFilters: ["list of event type filters"]
+  }){
+    errors
+  }
+}
+```
+
+Event type filters are removed if:
+
+- The returned `errors` object is empty.
+- The API responds with `200 OK`.
+
 ## Payload schema
 
 > Documentation for an audit event streaming schema was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358149) in GitLab 15.3.
diff --git a/doc/administration/issue_closing_pattern.md b/doc/administration/issue_closing_pattern.md
index f8b486fb1ec..bdbcdd0093c 100644
--- a/doc/administration/issue_closing_pattern.md
+++ b/doc/administration/issue_closing_pattern.md
@@ -86,7 +86,7 @@ To change the default issue closing pattern:
    docker compose up -d
    ```
 
-:::TabTitle Self-compiled (Source)
+:::TabTitle Self-compiled (source)
 
 1. Edit `/home/git/gitlab/config/gitlab.yml` and change the `issue_closing_pattern` value:
 
diff --git a/doc/api/groups.md b/doc/api/groups.md
index 94febd0ac0d..663296d9241 100644
--- a/doc/api/groups.md
+++ b/doc/api/groups.md
@@ -1158,7 +1158,7 @@ Parameters:
 The response is `202 Accepted` if the user has authorization.
 
 NOTE:
-A GitLab.com group can't be removed if it is linked to a subscription. To remove such a group, first [link the subscription](../subscriptions/index.md#change-the-linked-namespace) with a different group.
+A GitLab.com group can't be removed if it is linked to a subscription. To remove such a group, first [link the subscription](../subscriptions/gitlab_com/index.md#change-the-linked-namespace) with a different group.
 
 ## Restore group marked for deletion **(PREMIUM)**
 
diff --git a/doc/ci/environments/external_deployment_tools.md b/doc/ci/environments/external_deployment_tools.md
index c22adde2016..ff3172f0e02 100644
--- a/doc/ci/environments/external_deployment_tools.md
+++ b/doc/ci/environments/external_deployment_tools.md
@@ -35,5 +35,54 @@ You can configure your tool to make a request to the GitLab [Deployment API](../
 NOTE:
 You can create a [project access token](../../user/project/settings/project_access_tokens.md) for the GitLab API authentication.
 
+### Example: Track deployments of ArgoCD
+
+You can use [ArgoCD webhook](https://argocd-notifications.readthedocs.io/en/stable/services/webhook/) to send deployment events to GitLab Deployment API.
+Here is an example setup that creates a `success` deployment record in GitLab when ArgoCD successfully deploys a new revision:
+
+1. Create a new webhook. You can save the following manifest file and apply it by `kubectl apply -n argocd -f <manifiest-file-path>`:
+
+    ```yaml
+    apiVersion: v1
+    kind: ConfigMap
+    metadata:
+      name: argocd-notifications-cm
+    data:
+      trigger.on-deployed: |
+        - description: Application is synced and healthy. Triggered once per commit.
+          oncePer: app.status.sync.revision
+          send:
+          - gitlab-deployment-status
+          when: app.status.operationState.phase in ['Succeeded'] and app.status.health.status == 'Healthy'
+      template.gitlab-deployment-status: |
+        webhook:
+          gitlab:
+            method: POST
+            path: /projects/<your-project-id>/deployments
+            body: |
+              {
+                "status": "success",
+                "environment": "production",
+                "sha": "{{.app.status.operationState.operation.sync.revision}}",
+                "ref": "main",
+                "tag": "false"
+              }
+      service.webhook.gitlab: |
+        url: https://gitlab.com/api/v4
+        headers:
+        - name: PRIVATE-TOKEN
+          value: <your-access-token>
+        - name: Content-type
+          value: application/json
+    ```
+
+1. Create a new subscription in your application:
+
+    ```shell
+    kubectl patch app <your-app-name> -n argocd -p '{"metadata": {"annotations": {"notifications.argoproj.io/subscribe.on-deployed.gitlab":""}}}' --type merge
+    ```
+
 NOTE:
-If you don't have an environment yet, you can [create a new environment](index.md#create-a-static-environment) in the UI or with the [Environment API](../../api/environments.md#create-a-new-environment).
+If a deployment wasn't created as expected, you can troubleshoot with [`argocd-notifications` tool](https://argocd-notifications.readthedocs.io/en/stable/troubleshooting/).
+For example, `argocd-notifications template notify gitlab-deployment-status <your-app-name> --recipient gitlab:argocd-notifications`
+triggers API request immediately and renders an error message from GitLab API server if any.
diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md
index fc9b477574c..10c139c0a1b 100644
--- a/doc/development/documentation/styleguide/index.md
+++ b/doc/development/documentation/styleguide/index.md
@@ -1496,16 +1496,19 @@ GitLab supports four installation methods:
 - Linux package (Omnibus)
 - Helm chart (Kubernetes)
 - Docker
-- Self-compiled (Source)
+- Self-compiled (source)
 
 Configuration procedures can require users to edit configuration files, reconfigure
 GitLab, or restart GitLab. In this case:
 
 - Use [tabs](#tabs) to differentiate among the various installation methods.
+- Use the installation methods names exactly as described in the previous list.
 - Use them in the order described below.
 - Indent the code blocks to line up with the list item they belong to.
 - Use the appropriate syntax highlighting for each code block (`ruby`, `shell`, or `yaml`).
 - For the YAML files, always include the parent settings.
+- The final step to reconfigure or restart GitLab can be used verbatim since it's
+  the same every time.
 
 You can copy and paste the following snippet when describing a configuration
 edit:
@@ -1545,7 +1548,7 @@ edit:
          name: gitlab.example.com
    ```
 
-1. Apply the new values:
+1. Save the file and apply the new values:
 
    ```shell
    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
@@ -1570,7 +1573,7 @@ edit:
    docker compose up -d
    ```
 
-:::TabTitle Self-compiled (Source)
+:::TabTitle Self-compiled (source)
 
 1. Edit `/home/git/gitlab/config/gitlab.yml`:
 
@@ -1629,7 +1632,7 @@ It renders as:
          name: gitlab.example.com
    ```
 
-1. Apply the new values:
+1. Save the file and apply the new values:
 
    ```shell
    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
@@ -1654,7 +1657,7 @@ It renders as:
    docker compose up -d
    ```
 
-:::TabTitle Self-compiled (Source)
+:::TabTitle Self-compiled (source)
 
 1. Edit `/home/git/gitlab/config/gitlab.yml`:
 
diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md
index fc148e546de..81419acb51f 100644
--- a/doc/integration/omniauth.md
+++ b/doc/integration/omniauth.md
@@ -55,7 +55,7 @@ To change these settings:
 
   :::TabTitle Linux package (Omnibus)
 
-  1. Edit `/etc/gitlab/gitlab.rb` and update the following section:
+  1. Edit `/etc/gitlab/gitlab.rb`:
 
      ```ruby
      # CAUTION!
@@ -67,7 +67,7 @@ To change these settings:
      gitlab_rails['omniauth_block_auto_created_users'] = true
      ```
 
-  1. Reconfigure GitLab:
+  1. Save the file and reconfigure GitLab:
 
      ```shell
      sudo gitlab-ctl reconfigure
@@ -96,22 +96,15 @@ To change these settings:
      For more details, see the
      [globals documentation](https://docs.gitlab.com/charts/charts/globals.html#omniauth).
 
-  1. Apply the new values:
+  1. Save the file and apply the new values:
 
      ```shell
      helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
      ```
 
-  :::TabTitle Self-compiled (Source)
+  :::TabTitle Self-compiled (source)
 
-  1. Open the configuration file:
-
-     ```shell
-     cd /home/git/gitlab
-     sudo -u git -H editor config/gitlab.yml
-     ```
-
-  1. Update the following section:
+  1. Edit `/home/git/gitlab/config/gitlab.yml`:
 
      ```yaml
      ## OmniAuth settings
@@ -132,9 +125,13 @@ To change these settings:
        block_auto_created_users: true
      ```
 
-  1. Restart GitLab:
+  1. Save the file and restart GitLab:
 
      ```shell
+     # For systems running systemd
+     sudo systemctl restart gitlab.target
+
+     # For systems running SysV init
      sudo service gitlab restart
      ```
 
diff --git a/doc/subscriptions/gitlab_com/index.md b/doc/subscriptions/gitlab_com/index.md
index 02810545409..4851090c592 100644
--- a/doc/subscriptions/gitlab_com/index.md
+++ b/doc/subscriptions/gitlab_com/index.md
@@ -221,6 +221,34 @@ amounts at which the alert displays.
 | 100-999               | 8% of seats have been used.                                            |
 | 1000+                 | 5% of seats have been used                                             |
 
+## Change the linked account
+
+To change the GitLab.com account linked to your Customers Portal account:
+
+1. Log in to the
+   [Customers Portal](https://customers.gitlab.com/customers/sign_in).
+1. In a separate browser tab, go to [GitLab SaaS](https://gitlab.com/users/sign_in) and ensure you
+   are not logged in.
+1. On the Customers Portal page, select **My account > Account details**.
+1. Under **Your GitLab.com account**, select **Change linked account**.
+1. Log in to the [GitLab SaaS](https://gitlab.com/users/sign_in) account you want to link to the Customers Portal
+   account.
+
+## Change the linked namespace
+
+To change the namespace linked to a subscription:
+
+1. Log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in) with a
+   [linked](#change-the-linked-account) GitLab SaaS account.
+1. Navigate to the **Manage Purchases** page.
+1. Select **Change linked namespace**.
+1. Select the desired group from the **This subscription is for** dropdown. For a group to appear here, you must have the Owner role for that group.
+1. Select **Proceed to checkout**.
+
+Subscription charges are calculated based on the total number of users in a group, including its subgroups and nested projects. If the [total number of users](#view-seat-usage) exceeds the number of seats in your subscription, your account is charged for the additional users and you need to pay for the overage before you can change the linked namespace.
+
+Only one namespace can be linked to a subscription.
+
 ## Upgrade your GitLab SaaS subscription tier
 
 To upgrade your [GitLab tier](https://about.gitlab.com/pricing/):
@@ -415,7 +443,7 @@ and for communicating directly with the relevant GitLab team members.
 
 If your credit card is declined when purchasing a GitLab subscription, possible reasons include:
 
-- The credit card details provided are incorrect.
+- The credit card details provided are incorrect. The most common cause for this is an incomplete or dummy address.
 - The credit card account has insufficient funds.
 - You are using a virtual credit card and it has insufficient funds, or has expired.
 - The transaction exceeds the credit limit.
diff --git a/doc/subscriptions/index.md b/doc/subscriptions/index.md
index 47c1f730746..aab4c87ce5b 100644
--- a/doc/subscriptions/index.md
+++ b/doc/subscriptions/index.md
@@ -73,11 +73,13 @@ With the [Customers Portal](https://customers.gitlab.com/) you can:
 - [Change account owner information](#change-account-owner-information)
 - [Change your company details](#change-your-company-details)
 - [Change your payment method](#change-your-payment-method)
-- [Change the linked account](#change-the-linked-account)
-- [Change the namespace the subscription is linked to](#change-the-linked-namespace)
+- [Change the linked account](gitlab_com/index.md#change-the-linked-account)
+- [Change the namespace the subscription is linked to](gitlab_com/index.md#change-the-linked-namespace)
 - [Change customers portal account password](#change-customers-portal-account-password)
 
-The Customers Portal is available only to customers who purchased their subscription from GitLab. If you made your purchase through a partner or reseller, you must contact them directly for assistance with your subscription.
+The Customers Portal is available only to customers who purchased their
+subscription from GitLab. If you made your purchase through a partner or
+reseller, you must contact them directly for assistance with your subscription.
 
 ### Change account owner information
 
@@ -132,40 +134,6 @@ method as the default:
 1. **Edit** the selected payment method and check the **Make default payment method** checkbox.
 1. Select **Save Changes**.
 
-### Change the linked account
-
-To change the GitLab.com account linked to your Customers Portal account:
-
-1. Log in to the
-   [Customers Portal](https://customers.gitlab.com/customers/sign_in).
-1. In a separate browser tab, go to [GitLab SaaS](https://gitlab.com) and ensure you
-   are not logged in.
-1. On the Customers Portal page, select **My account > Account details**.
-1. Under **Your GitLab.com account**, select **Change linked account**. If the account is not yet linked, select **Link my GitLab.com account**.
-1. Log in to the [GitLab SaaS](https://gitlab.com) account you want to link to the Customers Portal
-   account.
-
-### Change the linked namespace
-
-To change the namespace linked to a subscription:
-
-1. Log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in) with a
-   [linked](#change-the-linked-account) GitLab SaaS account.
-1. Navigate to the **Manage Purchases** page.
-1. Select **Change linked namespace**.
-1. Select the desired group from the **Select user or group** dropdown list. For a group to appear
-   here, you must have the Owner role for that group.
-1. Select **Proceed to checkout**.
-
-If the group you want to link does not appear in the dropdown list, check:
-
-- You have [linked your Customers Portal account with your GitLab.com account](#change-the-linked-account).
-- That the linked account is a member of the group you want to select, and you are assigned the Owner role.
-
-Subscription charges are calculated based on the total number of users in a group, including its subgroups and nested projects. If the [total number of users](gitlab_com/index.md#view-seat-usage) exceeds the number of seats in your subscription, your account is charged for the additional users and you need to pay for the overage before you can change the linked namespace.
-
-Only one namespace can be linked to a subscription.
-
 ### Change Customers Portal account password
 
 To change the password for this customers portal account:
diff --git a/doc/user/packages/container_registry/reduce_container_registry_storage.md b/doc/user/packages/container_registry/reduce_container_registry_storage.md
index 23d835ddf5f..cbf9af633ac 100644
--- a/doc/user/packages/container_registry/reduce_container_registry_storage.md
+++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md
@@ -4,17 +4,18 @@ group: Container Registry
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
 ---
 
-# Reduce Container Registry Storage **(FREE)**
+# Reduce Container Registry storage **(FREE)**
 
-Container registries become large over time without cleanup. When a large number of images or tags are added:
+Container registries can grow in size over time if you don't manage your registry usage. For example,
+if you add a large number of images or tags:
 
-- Fetching the list of available tags or images becomes slower.
+- Retrieving the list of available tags or images becomes slower.
 - They take up a large amount of storage space on the server.
 
-We recommend deleting unnecessary images and tags and setting up a [cleanup policy](#cleanup-policy)
+You should delete unnecessary images and tags and set up a [cleanup policy](#cleanup-policy)
 to automatically manage your container registry usage.
 
-## Check Container Registry Storage Use
+## Check Container Registry storage use
 
 The Usage Quotas page (**Settings > Usage Quotas > Storage**) displays storage usage for Packages.
 This page includes the Container Registry usage, which is only available on GitLab.com.
@@ -23,10 +24,16 @@ metadata database. Support for improvements is proposed in epic [5523](https://g
 You cannot use the Container Registry in self-managed instances, but epic [5521](https://gitlab.com/groups/gitlab-org/-/epics/5521) proposes to change this behavior.
 
 Image layers stored in the Container Registry are deduplicated at the root namespace level.
-If you tag the same image more than once in the same repository or across distinct
-repositories under the same root namespace, it is only counted once.
-If an image layer is shared across multiple images, in the same
-container repository, project, group, or across different repositories, it is only counted once.
+
+An image is only counted once if:
+
+- You tag the same image more than once in the same repository.
+- You tag the same image across distinct repositories under the same root namespace.
+
+An image layer is only counted once if:
+
+- You share the image layer across multiple images in the same container repository, project, or group.
+- You share the image layer across different repositories.
 
 Only layers that are referenced by tagged images are accounted for. Untagged images and any layers
 referenced exclusively by them are subject to [online garbage collection](index.md#delete-images).
@@ -50,7 +57,7 @@ To delete the underlying layers and images that aren't associated with any tags,
 
 ### Enable the cleanup policy
 
-Cleanup policies can be run on all projects, with these exceptions:
+You can run cleanup policies on all projects with these exceptions:
 
 - For self-managed GitLab instances, the project must have been created
   in GitLab 12.8 or later. However, an administrator can enable the cleanup policy
@@ -63,7 +70,7 @@ Cleanup policies can be run on all projects, with these exceptions:
   ApplicationSetting.last.update(container_expiration_policies_enable_historic_entries: true)
   ```
 
-  Enabling cleanup policies on all project can impact performance, especially if you
+  Enabling cleanup policies on all projects can impact performance, especially if you
   are using an [external registry](#use-with-external-container-registries).
 
 WARNING:
@@ -72,34 +79,34 @@ GitLab.com that don't have a container image.
 
 ### How the cleanup policy works
 
-The cleanup policy collects all tags in the Container Registry and excludes tags
-until only the tags to be deleted remain.
+The cleanup policy collects all tags in the Container Registry and excludes tags until the only
+tags you want to delete remain.
 
 The cleanup policy searches for images based on the tag name. Support for full path matching is tracked in issue [281071](https://gitlab.com/gitlab-org/gitlab/-/issues/281071).
 
 The cleanup policy:
 
 1. Collects all tags for a given repository in a list.
-1. Excludes the tag named `latest` from the list.
-1. Evaluates the `name_regex` (tags to expire), excluding non-matching names from the list.
-1. Excludes from the list any tags matching the `name_regex_keep` value (tags to preserve).
+1. Excludes the tag named `latest`.
+1. Evaluates the `name_regex` (tags to expire), excluding non-matching names.
+1. Excludes any tags matching the `name_regex_keep` value (tags to preserve).
 1. Excludes any tags that do not have a manifest (not part of the options in the UI).
 1. Orders the remaining tags by `created_date`.
-1. Excludes from the list the N tags based on the `keep_n` value (Number of tags to retain).
-1. Excludes from the list the tags more recent than the `older_than` value (Expiration interval).
-1. Finally, the remaining tags in the list are deleted from the Container Registry.
+1. Excludes the N tags based on the `keep_n` value (Number of tags to retain).
+1. Excludes the tags more recent than the `older_than` value (Expiration interval).
+1. Deletes the remaining tags in the list from the Container Registry.
 
 WARNING:
 On GitLab.com, the execution time for the cleanup policy is limited. Some tags may remain in
 the Container Registry after the policy runs. The next time the policy runs, the remaining tags are included.
-It may take multiple runs for all tags to be deleted.
+It may take multiple runs to delete all tags.
 
 WARNING:
 GitLab self-managed installations support third-party container registries that comply with the
 [Docker Registry HTTP API V2](https://docs.docker.com/registry/spec/api/)
-specification. However, this specification does not include a tag delete operation. Therefore, when
-interacting with third-party container registries, GitLab uses a workaround to delete tags. See the
-[related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/15737)
+specification. However, this specification does not include a tag delete operation. Therefore, GitLab uses a
+workaround to delete tags when interacting with third-party container registries. Refer to
+issue [15737](https://gitlab.com/gitlab-org/gitlab/-/issues/15737)
 for more information. Due to possible implementation variations, this workaround is not guaranteed
 to work with all third-party registries in the same predictable way. If you use the GitLab Container
 Registry, this workaround is not required because we implemented a special tag delete operation. In
@@ -115,18 +122,18 @@ To create a cleanup policy in the UI:
 1. Expand the **Clean up image tags** section.
 1. Complete the fields.
 
-   | Field                                                                     | Description                                                                                                       |
-   |---------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|
-   | **Toggle** | Turn the policy on or off. |
-   | **Run cleanup** | How often the policy should run. |
-   | **Keep the most recent** | How many tags to _always_ keep for each image. |
-   | **Keep tags matching** | The regex pattern that determines which tags to preserve. The `latest` tag is always preserved. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). |
-   | **Remove tags older than** | Remove only tags older than X days. |
-   | **Remove tags matching**  | The regex pattern that determines which tags to remove. This value cannot be blank. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). |
+   | Field                      | Description                                     |
+   |----------------------------|-------------------------------------------------|
+   | **Toggle**                 | Turn the policy on or off.                      |
+   | **Run cleanup**            | How often the policy should run.                |
+   | **Keep the most recent**   | How many tags to _always_ keep for each image.  |
+   | **Keep tags matching**     | A regex pattern that determines which tags to preserve. The `latest` tag is always preserved. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). |
+   | **Remove tags older than** | Remove only tags older than X days.             |
+   | **Remove tags matching**   | A regex pattern that determines which tags to remove. This value cannot be blank. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples).             |
 
 1. Select **Save**.
 
-Depending on the interval you chose, the policy is scheduled to run.
+The policy runs on the scheduled interval you selected.
 
 NOTE:
 If you edit the policy and select **Save** again, the interval is reset.
@@ -135,7 +142,8 @@ If you edit the policy and select **Save** again, the interval is reset.
 
 Cleanup policies use regex patterns to determine which tags should be preserved or removed, both in the UI and the API.
 
-Regex patterns are automatically surrounded with `\A` and `\Z` anchors. Do not include any `\A`, `\Z`, `^` or `$` token in the regex patterns as they are not necessary.
+Regex patterns are automatically surrounded with `\A` and `\Z` anchors. Therefore, you do not need to include any
+`\A`, `\Z`, `^` or `$` tokens in the regex patterns.
 
 Here are some examples of regex patterns you can use:
 
@@ -180,17 +188,17 @@ Here are some examples of regex patterns you can use:
 Cleanup policies are executed as a background process. This process is complex, and depending on the number of tags to delete,
 the process can take time to finish.
 
-To prevent server resource starvation, the following application settings are available:
+You can use the following application settings to prevent server resource starvation:
 
 - `container_registry_expiration_policies_worker_capacity`: the maximum number of cleanup workers
-  running concurrently. This must be greater than or equal to `0`. We recommend starting with a low
-  number and increasing it after monitoring the resources used by the background workers. To remove
+  running concurrently. This value must be greater than or equal to `0`. You should start with a low
+  number and increase it after monitoring the resources used by the background workers. To remove
   all workers and not execute the cleanup policies, set this to `0`. The default value is `4`.
 - `container_registry_delete_tags_service_timeout`: the maximum time (in seconds) that the cleanup
   process can take to delete a batch of tags. The default value is `250`.
 - `container_registry_cleanup_tags_service_max_list_size`: the maximum number of tags that can be
-  deleted in a single execution. Additional tags must be deleted in another execution. We recommend
-  starting with a low number and increasing it after monitoring that container images are properly
+  deleted in a single execution. Additional tags must be deleted in another execution. You should
+  start with a low number and increase it after verifying that container images are properly
   deleted. The default value is `200`.
 - `container_registry_expiration_policies_caching`: enable or disable tag creation timestamp caching
   during execution of policies. Cached timestamps are stored in [Redis](../../../development/architecture.md#redis).
@@ -213,7 +221,8 @@ You can set, update, and disable the cleanup policies using the GitLab API.
 
 Examples:
 
-- Select all tags, keep at least 1 tag per image, clean up any tag older than 14 days, run once a month, preserve any images with the name `main` and the policy is enabled:
+- Select all tags, keep at least 1 tag per image, clean up any tag older than 14 days, run once a month, preserve
+any images with the name `main`, and the policy is enabled:
 
   ```shell
   curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: <your_access_token>" \
@@ -251,14 +260,14 @@ See the API documentation for further details: [Edit project API](../../../api/p
 
 When using an [external container registry](../../../administration/packages/container_registry.md#use-an-external-container-registry-with-gitlab-as-an-auth-endpoint),
 running a cleanup policy on a project may have some performance risks.
-If a project runs a policy to remove thousands of tags
+If a project runs a policy to remove thousands of tags,
 the GitLab background jobs may get backed up or fail completely.
-For projects created before GitLab 12.8, we recommend you enable container cleanup policies
+For projects created before GitLab 12.8, you should enable container cleanup policies
 only if the number of tags being cleaned up is minimal.
 
 ## More Container Registry storage reduction options
 
-Here are some other options to reduce your project's use of Container Registry storage:
+Here are some other options you can use to reduce the Container Registry storage used by your project:
 
 - Use the [GitLab UI](index.md#delete-images)
   to delete individual image tags or the entire repository containing all the tags.
@@ -330,6 +339,10 @@ the tags. To create the list and delete the tags:
 1. Remove any tags that you want to keep from the `list_o_tags.out` file. For example, you can use `sed` to
    parse the file and remove the tags.
 
+   ::Tabs
+
+   :::TabTitle Linux
+
    ```shell
    # Remove the `latest` tag from the file
    sed -i '/latest/d' list_o_tags.out
@@ -344,12 +357,24 @@ the tags. To create the list and delete the tags:
    sed -i '/_v3$/d' list_o_tags.out
    ```
 
-   If you are running macOS, you must add `.bak` to the commands. For example:
+   :::TabTitle macOS
 
    ```shell
+   # Remove the `latest` tag from the file
    sed -i .bak '/latest/d' list_o_tags.out
+
+   # Remove the first N tags from the file
+   sed -i .bak '1,Nd' list_o_tags.out
+
+   # Remove the tags starting with `Av` from the file
+   sed -i .bak '/^Av/d' list_o_tags.out
+
+   # Remove the tags ending with `_v3` from the file
+   sed -i .bak '/_v3$/d' list_o_tags.out
    ```
 
+   ::EndTabs
+
 1. Double-check the `list_o_tags.out` file to make sure it contains only the tags that you want to
    delete.