• Valid access levels
• List protected tags
• Get a single protected tag or wildcard protected tag
• Protect repository tags
  • Example with user and group access
• Unprotect repository tags
• Related topics

Protected tags API

Valid access levels

These access levels are recognized:

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

List protected tags

Gets 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

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "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 single protected tag or wildcard protected tag

Gets a single protected tag or wildcard protected tag.

GET /projects/:id/protected_tags/:name

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "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 repository tags

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

POST /projects/:id/protected_tags

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/protected_tags" -d '{
   "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>" "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"

The 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

Unprotects the given protected tag or wildcard protected tag.

DELETE /projects/:id/protected_tags/:name

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

Related topics

• Tags API for all tags
• Tags user documentation
• Protected tags user documentation