Skip to content

Protected packages API

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed Status: Experiment

FLAG: 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 manages the protection rules for packages. This feature is an experiment.

List package protection rules

Gets a list of package protection rules from a project.

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

Can return the following status codes:

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

Example response:

[
 {
  "id": 1,
  "project_id": 7,
  "package_name_pattern": "@flightjs/flight-package-0",
  "package_type": "npm",
  "minimum_access_level_for_push": "maintainer"
 },
 {
  "id": 2,
  "project_id": 7,
  "package_name_pattern": "@flightjs/flight-package-1",
  "package_type": "npm",
  "minimum_access_level_for_push": "maintainer"
 }
]

Create a package protection rule

Create a package protection rule for a project.

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

Supported attributes:

Attribute Type Required Description
id integer/string Yes ID or URL-encoded path of the project.
package_name_pattern string Yes Package name protected by the protection rule. For example @my-scope/my-package-*. Wildcard character * allowed.
package_type string Yes Package type protected by the protection rule. For example npm.
minimum_access_level_for_push string Yes Minimum GitLab access level able to push a package. Must be at least maintainer. For example maintainer, owner or admin.

If successful, returns 201 and the created package protection rule.

Can return the following status codes:

  • 201 Created: The package protection rule was created successfully.
  • 400 Bad Request: The package protection rule is invalid.
  • 401 Unauthorized: The access token is invalid.
  • 403 Forbidden: The user does not have permission to create a package protection rule.
  • 404 Not Found: The project was not found.
  • 422 Unprocessable Entity: The package protection rule could not be created, for example, because the package_name_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/packages/protection/rules" \
  --data '{
       "package_name_pattern": "package-name-pattern-*",
       "package_type": "npm",
       "minimum_access_level_for_push": "maintainer"
    }'

Update a package protection rule

Update a package protection rule for a project.

PATCH /api/v4/projects/:id/packages/protection/rules/:package_protection_rule_id

Supported attributes:

Attribute Type Required Description
id integer/string Yes ID or URL-encoded path of the project.
package_protection_rule_id integer Yes ID of the package protection rule to be updated.
package_name_pattern string No Package name protected by the protection rule. For example @my-scope/my-package-*. Wildcard character * allowed.
package_type string No Package type protected by the protection rule. For example npm.
minimum_access_level_for_push string No Minimum GitLab access level able to push a package. Must be at least maintainer. For example maintainer, owner or admin.

If successful, returns 200 and the updated package protection rule.

Can return the following status codes:

  • 200 OK: The package 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 a package protection rule.
  • 404 Not Found: The project was not found.
  • 422 Unprocessable Entity: The package protection rule could not be patched, for example, because the package_name_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/packages/protection/rules/32" \
  --data '{
       "package_name_pattern": "new-package-name-pattern-*"
    }'

Delete a package protection rule

Deletes a package protection rule from a project.

DELETE /api/v4/projects/:id/packages/protection/rules/:package_protection_rule_id

Supported attributes:

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

If successful, returns 204 No Content.

Can return the following status codes:

  • 204 No Content: The package protection rule was deleted successfully.
  • 400 Bad Request: The id or the package_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 package protection rule.
  • 404 Not Found: The project or the package 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/packages/protection/rules/32"