Container registry protection rules API

Tier: Free, Premium, Ultimate Offering: Self-managed Status: Experiment
History
  • Introduced in GitLab 17.2 with a flag named container_registry_protected_containers. Disabled by default.
The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.

This API endpoint manages the protection rules for container registries in a project. This feature is an experiment.

List container registry protection rules

Gets a list of container registry protection rules from a project. 

GET /api/v4/projects/:id/registry/protection/rules

Supported attributes:

Attribute Type Required Description
id integer/string Yes ID or URL-encoded path of the project.

If successful, returns 200 and a list of container registry protection rules.

Can return the following status codes:

  • 200 OK: A list of container registry protection rules.
  • 401 Unauthorized: The access token is invalid.
  • 403 Forbidden: The user does not have permission to list container registry protection rules for this project.
  • 404 Not Found: The project was not found.

Example request: 

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/7/registry/protection/rules"

Example response: 

[
  {
    "id": 1,
    "project_id": 7,
    "repository_path_pattern": "flightjs/flight0",
    "minimum_access_level_for_push": "maintainer",
    "minimum_access_level_for_delete": "maintainer"
  },
  {
    "id": 2,
    "project_id": 7,
    "repository_path_pattern": "flightjs/flight1",
    "minimum_access_level_for_push": "maintainer",
    "minimum_access_level_for_delete": "maintainer"
  },
]

Create a container registry protection rule

History

Create a container registry protection rule for a project. 

POST /api/v4/projects/:id/registry/protection/rules

Supported attributes:

Attribute Type Required Description
id integer/string Yes ID or URL-encoded path of the project.
repository_path_pattern string Yes Container repository path pattern protected by the protection rule. For example flight/flight-*. Wildcard character * allowed.
minimum_access_level_for_push string No Minimum GitLab access level to allow to push container images to the container registry. For example maintainer, owner or admin. Must be provided when minimum_access_level_for_delete is not set.
minimum_access_level_for_delete string No Minimum GitLab access level to allow to delete container images in the container registry. For example maintainer, owner, admin. Must be provided when minimum_access_level_for_push is not set.

If successful, returns 201 and the created container registry protection rule.

Can return the following status codes:

  • 201 Created: The container registry protection rule was created successfully.
  • 400 Bad Request: The container registry protection rule is invalid.
  • 401 Unauthorized: The access token is invalid.
  • 403 Forbidden: The user does not have permission to create a container registry protection rule.
  • 404 Not Found: The project was not found.
  • 422 Unprocessable Entity: The container registry protection rule could not be created, for example, because the repository_path_pattern is already taken.

Example request: 

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/projects/7/registry/protection/rules" \
  --data '{
        "repository_path_pattern": "flightjs/flight-needs-to-be-a-unique-path",
        "minimum_access_level_for_push": "maintainer",
        "minimum_access_level_for_delete": "maintainer"
    }'

Update a container registry protection rule

History

Update a container registry protection rule for a project. 

PATCH /api/v4/projects/:id/registry/protection/rules/:protection_rule_id

Supported attributes:

Attribute Type Required Description
id integer/string Yes ID or URL-encoded path of the project.
protection_rule_id integer Yes ID of the protection rule to be updated.
repository_path_pattern string No Container repository path pattern protected by the protection rule. For example flight/flight-*. Wildcard character * allowed.
minimum_access_level_for_push string No Minimum GitLab access level to allow to push container images to the container registry. For example maintainer, owner or admin. Must be provided when minimum_access_level_for_delete is not set. To unset the value, use an empty string "".
minimum_access_level_for_delete string No Minimum GitLab access level to allow to delete container images in the container registry. For example maintainer, owner, admin. Must be provided when minimum_access_level_for_push is not set. To unset the value, use an empty string "".

If successful, returns 200 and the updated protection rule.

Can return the following status codes:

  • 200 OK: The protection rule was patched successfully.
  • 400 Bad Request: The patch is invalid.
  • 401 Unauthorized: The access token is invalid.
  • 403 Forbidden: The user does not have permission to patch the protection rule.
  • 404 Not Found: The project was not found.
  • 422 Unprocessable Entity: The protection rule could not be patched, for example, because the repository_path_pattern is already taken.

Example request: 

curl --request PATCH \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/projects/7/registry/protection/rules/32" \
  --data '{
       "repository_path_pattern": "flight/flight-*"
    }'

Delete a container registry protection rule

History

Deletes a container registry protection rule from a project. 

DELETE /api/v4/projects/:id/registry/protection/rules/:protection_rule_id

Supported attributes:

Attribute Type Required Description
id integer/string Yes ID or URL-encoded path of the project.
protection_rule_id integer Yes ID of the container registry protection rule to be deleted.

If successful, returns 204 No Content.

Can return the following status codes:

  • 204 No Content: The protection rule was deleted successfully.
  • 400 Bad Request: The id or the protection_rule_id are missing or are invalid.
  • 401 Unauthorized: The access token is invalid.
  • 403 Forbidden: The user does not have permission to delete the protection rule.
  • 404 Not Found: The project or the protection rule was not found.

Example request: 

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/7/registry/protection/rules/1"