Protected packages API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed
History

This API manages the protection rules for packages.

List package protection rules

Gets a list of package protection rules from a project.

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

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringYesID 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:

AttributeTypeRequiredDescription
idinteger/stringYesID or URL-encoded path of the project.
package_name_patternstringYesPackage name protected by the protection rule. For example @my-scope/my-package-*. Wildcard character * allowed.
package_typestringYesPackage type protected by the protection rule. For example npm.
minimum_access_level_for_pushstringYesMinimum 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:

AttributeTypeRequiredDescription
idinteger/stringYesID or URL-encoded path of the project.
package_protection_rule_idintegerYesID of the package protection rule to be updated.
package_name_patternstringNoPackage name protected by the protection rule. For example @my-scope/my-package-*. Wildcard character * allowed.
package_typestringNoPackage type protected by the protection rule. For example npm.
minimum_access_level_for_pushstringNoMinimum 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:

AttributeTypeRequiredDescription
idinteger/stringYesID or URL-encoded path of the project.
package_protection_rule_idintegerYesID 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"