Protected tags API

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

Valid access levels

These access levels are recognized:

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

List protected tags

History

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.

Copy to clipboard
GET /projects/:id/protected_tags
AttributeTypeRequiredDescription
idinteger or stringyesThe ID or URL-encoded path of the project.
Copy to clipboard
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.example.com/api/v4/projects/5/protected_tags"

Example response:

Copy to clipboard
[
  {
    "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.

Copy to clipboard
GET /projects/:id/protected_tags/:name
AttributeTypeRequiredDescription
idinteger or stringyesThe ID or URL-encoded path of the project.
namestringyesThe name of the tag or wildcard.
Copy to clipboard
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.example.com/api/v4/projects/5/protected_tags/release-1-0"

Example response:

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

Protect repository tags

History

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

Copy to clipboard
POST /projects/:id/protected_tags
Copy to clipboard
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"
}'
AttributeTypeRequiredDescription
idinteger or stringyesThe ID or URL-encoded path of the project.
namestringyesThe name 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_levelstringnoAccess levels allowed to create. Default: 40, for Maintainer role.

Example response:

Copy to clipboard
{
  "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:

Copy to clipboard
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.
Copy to clipboard
{
  "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.

Copy to clipboard
DELETE /projects/:id/protected_tags/:name
Copy to clipboard
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.example.com/api/v4/projects/5/protected_tags/*-stable"
AttributeTypeRequiredDescription
idinteger or stringyesThe ID or URL-encoded path of the project.
namestringyesThe name of the tag.