Protected tags API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Use this API to manage protected tags for your repositories.

Valid access levels

These access levels are recognized:

  • 0: No access
  • 30: Developer role
  • 40: Maintainer role

List protected tags

Get a list of protected tags from a project. This function takes pagination parameters page and per_page to restrict the list of protected tags.

GET /projects/:id/protected_tags

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringYesID or URL-encoded path of the project.

If successful, returns 200 OK and the following response attributes:

AttributeTypeDescription
create_access_levelsarrayArray of create access level configurations.
create_access_levels[].access_levelintegerAccess level for creating tags.
create_access_levels[].access_level_descriptionstringHuman-readable description of the access level.
create_access_levels[].deploy_key_idintegerID of the deploy key with create access.
create_access_levels[].group_idintegerID of the group with create access. Premium and Ultimate only.
create_access_levels[].idintegerID of the create access level configuration.
create_access_levels[].user_idintegerID of the user with create access. Premium and Ultimate only.
namestringName of the protected tag.

Example request:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/protected_tags"

Example response:

[
  {
    "name": "release-1-0",
    "create_access_levels": [
      {
        "id":1,
        "access_level": 40,
        "access_level_description": "Maintainers"
      },
      {
        "id": 2,
        "access_level": 40,
        "access_level_description": "Deploy key",
        "deploy_key_id": 1
      }
    ]
  }
]

Get a protected tag or wildcard protected tag

Get a single protected tag or wildcard protected tag.

GET /projects/:id/protected_tags/:name

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringYesID or URL-encoded path of the project.
namestringYesName of the tag or wildcard.

If successful, returns 200 OK and the following response attributes:

AttributeTypeDescription
create_access_levelsarrayArray of create access level configurations.
create_access_levels[].access_levelintegerAccess level for creating tags.
create_access_levels[].access_level_descriptionstringHuman-readable description of the access level.
create_access_levels[].deploy_key_idintegerID of the deploy key with create access.
create_access_levels[].group_idintegerID of the group with create access. Premium and Ultimate only.
create_access_levels[].idintegerID of the create access level configuration.
create_access_levels[].user_idintegerID of the user with create access. Premium and Ultimate only.
namestringName of the protected tag.

Example request:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/protected_tags/release-1-0"

Example response:

{
  "name": "release-1-0",
  "create_access_levels": [
    {
      "id": 1,
      "access_level": 40,
      "access_level_description": "Maintainers"
    }
  ]
}

Protect a repository tag

Protect a single repository tag, or several project repository tags, using a wildcard protected tag.

POST /projects/:id/protected_tags

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringYesID or URL-encoded path of the project.
namestringYesName of the tag or wildcard.
allowed_to_createarrayNoArray of access levels allowed to create tags, with each described by a hash of the form {user_id: integer}, {group_id: integer}, {deploy_key_id: integer}, or {access_level: integer}. Premium and Ultimate only.
create_access_levelintegerNoAccess levels allowed to create. Default is 40 (Maintainer role).

If successful, returns 201 Created and the following response attributes:

AttributeTypeDescription
create_access_levelsarrayArray of create access level configurations.
create_access_levels[].access_levelintegerAccess level for creating tags.
create_access_levels[].access_level_descriptionstringHuman-readable description of the access level.
create_access_levels[].deploy_key_idintegerID of the deploy key with create access.
create_access_levels[].group_idintegerID of the group with create access. Premium and Ultimate only.
create_access_levels[].idintegerID of the create access level configuration.
create_access_levels[].user_idintegerID of the user with create access. Premium and Ultimate only.
namestringName of the protected tag.

Example request:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/projects/5/protected_tags" \
  --data '{
   "allowed_to_create" : [
      {
         "user_id" : 1
      },
      {
         "access_level" : 30
      }
   ],
   "create_access_level" : 30,
   "name" : "*-stable"
}'

Example response:

{
  "name": "*-stable",
  "create_access_levels": [
    {
      "id": 1,
      "access_level": 30,
      "access_level_description": "Developers + Maintainers"
    }
  ]
}

Example with user and group access

Elements in the allowed_to_create array should take the form {user_id: integer}, {group_id: integer}, {deploy_key_id: integer}, or {access_level: integer}. Each user must have access to the project and each group must have this project shared. These access levels allow more granular control over protected tag access. For more information, see Add a group to protected tags.

This example request demonstrates how to create a protected tag that allows creation access to a specific user and group:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/protected_tags?name=*-stable&allowed_to_create%5B%5D%5Buser_id%5D=10&allowed_to_create%5B%5D%5Bgroup_id%5D=20"

This example response includes:

  • A protected tag with name "*-stable".
  • create_access_levels with ID 1 for user with ID 10.
  • create_access_levels with ID 2 for group with ID 20.
{
  "name": "*-stable",
  "create_access_levels": [
    {
      "id": 1,
      "access_level": null,
      "user_id": 10,
      "group_id": null,
      "access_level_description": "Administrator"
    },
    {
      "id": 2,
      "access_level": null,
      "user_id": null,
      "group_id": 20,
      "access_level_description": "Example Create Group"
    }
  ]
}

Unprotect repository tags

Unprotect the given protected tag or wildcard protected tag.

DELETE /projects/:id/protected_tags/:name

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringYesID or URL-encoded path of the project.
namestringYesName of the tag.

If successful, returns 204 No Content.

Example request:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/protected_tags/*-stable"