diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md
index cf5a7f89c8bc40c09ff6414afe6cc2ff5dd89039..12bdeebca1db385be0f915fa586067778b2c66fd 100644
--- a/doc/api/container_registry.md
+++ b/doc/api/container_registry.md
@@ -30,6 +30,55 @@ To disable it:
Feature.disable(:ci_job_token_scope)
```
+## Change the visibility of the Container Registry
+
+This controls who can view the Container Registry.
+
+```plaintext
+PUT /projects/:id/
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) accessible by the authenticated user. |
+| `container_registry_access_level` | string | no | The desired visibility of the Container Registry. One of `enabled` (default), `private`, or `disabled`. |
+
+Descriptions of the possible values for `container_registry_access_level`:
+
+- **enabled** (Default): The Container Registry is visible to everyone with access to the project.
+If the project is public, the Container Registry is also public. If the project is internal or
+private, the Container Registry is also internal or private.
+
+- **private**: The Container Registry is visible only to project members with Reporter role or
+higher. This is similar to the behavior of a private project with Container Registry visibility set
+to **enabled**.
+
+- **disabled**: The Container Registry is disabled.
+
+See the [Container Registry visibility permissions](../user/packages/container_registry/index.md#container-registry-visibility-permissions)
+for more details about the permissions that this setting grants to users.
+
+```shell
+curl --request PUT "https://gitlab.example.com/api/v4/projects/5/" \
+ --header 'PRIVATE-TOKEN: <your_access_token>' \
+ --header 'Accept: application/json' \
+ --header 'Content-Type: application/json' \
+ --data-raw '{
+ "container_registry_access_level": "private"
+ }'
+```
+
+Example response:
+
+```json
+{
+ "id": 5,
+ "name": "Project 5",
+ "container_registry_access_level": "private",
+ ...
+}
+```
+
## List registry repositories
### Within a project
diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md
index 4bf86e0a6d4e929c28be4f978e16b9001301361f..18b86c4a357e5cf68b33213936fc124d2634b07f 100644
--- a/doc/user/packages/container_registry/index.md
+++ b/doc/user/packages/container_registry/index.md
@@ -745,10 +745,13 @@ You can, however, remove the Container Registry for a project:
The **Packages & Registries > Container Registry** entry is removed from the project's sidebar.
-## Set visibility of the Container Registry
+## Change visibility of the Container Registry
By default, the Container Registry is visible to everyone with access to the project.
-You can, however, change the visibility of the Container Registry for a project:
+You can, however, change the visibility of the Container Registry for a project.
+
+See the [Container Registry visibility permissions](#container-registry-visibility-permissions)
+for more details about the permissions that this setting grants to users.
1. Go to your project's **Settings > General** page.
1. Expand the section **Visibility, project features, permissions**.
@@ -764,6 +767,25 @@ You can, however, change the visibility of the Container Registry for a project:
1. Select **Save changes**.
+## Container Registry visibility permissions
+
+The ability to view the Container Registry and pull images is controlled by the Container Registry's
+visibility permissions. You can change this through the [visibility setting on the UI](#change-visibility-of-the-container-registry)
+or the [API](../../../api/container_registry.md#change-the-visibility-of-the-container-registry).
+[Other permissions](../../permissions.md)
+such as updating the Container Registry, pushing or deleting images, and so on are not affected by
+this setting. However, disabling the Container Registry disables all Container Registry operations.
+
+| | | Anonymous<br/>(Everyone on internet) | Guest | Reporter, Developer, Maintainer, Owner |
+| -------------------- | --------------------- | --------- | ----- | ------------------------------------------ |
+| Public project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | Yes | Yes | Yes |
+| Public project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes |
+| Internal project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | No | Yes | Yes |
+| Internal project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes |
+| Private project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | No | No | Yes |
+| Private project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes |
+| Any project with Container Registry `disabled` | All operations on Container Registry | No | No | No |
+
## Manifest lists and garbage collection
Manifest lists are commonly used for creating multi-architecture images. If you rely on manifest
diff --git a/doc/user/permissions.md b/doc/user/permissions.md
index e73aa93d5ecfb909e33a3a9980894bd42569cdbf..e47c70ba2f24631d625d2fea4fc2bb9908384362 100644
--- a/doc/user/permissions.md
+++ b/doc/user/permissions.md
@@ -94,7 +94,6 @@ The following table lists project permissions available for each role:
| Pull [packages](packages/index.md) | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ |
| Reopen [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ |
| See a commit status | | ✓ | ✓ | ✓ | ✓ |
-| See a container registry | | ✓ | ✓ | ✓ | ✓ |
| See a list of merge requests | | ✓ | ✓ | ✓ | ✓ |
| See environments | | ✓ | ✓ | ✓ | ✓ |
| [Set issue estimate and record time spent](project/time_tracking.md) | | ✓ | ✓ | ✓ | ✓ |
@@ -260,6 +259,11 @@ Read through the documentation on [permissions for File Locking](project/file_lo
as well as by guest users that create a confidential issue. To learn more,
read through the documentation on [permissions and access to confidential issues](project/issues/confidential_issues.md#permissions-and-access-to-confidential-issues).
+### Container Registry visibility permissions
+
+Find the visibility permissions for the Container Registry, as described in the
+[related documentation](packages/container_registry/index.md#container-registry-visibility-permissions).
+
## Group members permissions
NOTE: