Container repository 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 protection rules for container repositories in a project’s container registry. This feature is an experiment.

List container repository protection rules

Gets a list of container repository protection rules from a project’s container registry. 

GET /api/v4/projects/:id/registry/protection/repository/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 repository protection rules.

Can return the following status codes:

  • 200 OK: A list of protection rules.
  • 401 Unauthorized: The access token is invalid.
  • 403 Forbidden: The user does not have permission to list 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 repository protection rule

History

Create a container repository protection rule for a project’s container registry. 

POST /api/v4/projects/:id/registry/protection/repository/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 required 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 required 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 repository protection rule.

Can return the following status codes:

  • 201 Created: The protection rule was created successfully.
  • 400 Bad Request: The protection rule is invalid.
  • 401 Unauthorized: The access token is invalid.
  • 403 Forbidden: The user does not have permission to create a protection rule.
  • 404 Not Found: The project was not found.
  • 422 Unprocessable Entity: The 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/repository/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 repository protection rule

History

Update a container repository protection rule for a project’s container registry. 

PATCH /api/v4/projects/:id/registry/protection/repository/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 required 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 required 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 updated successfully.
  • 400 Bad Request: The protection rule is invalid.
  • 401 Unauthorized: The access token is invalid.
  • 403 Forbidden: The user does not have permission to update the protection rule.
  • 404 Not Found: The project was not found.
  • 422 Unprocessable Entity: The protection rule could not be updated. 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/repository/rules/32" \
  --data '{
       "repository_path_pattern": "flight/flight-*"
    }'

Delete a container repository protection rule

History

Deletes a container repository protection rule from a project’s container registry. 

DELETE /api/v4/projects/:id/registry/protection/repository/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 repository 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/repository/rules/1"