Merge branch '18792-add-container-registry-api-docs' into 'master'

Add docs about changing container registry visibility

See merge request gitlab-org/gitlab!67413

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

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

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: