Protected tags API

Tier: Free, Premium, Ultimate Offering: GitLab.com, 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
  • Deploy key information introduced in GitLab 16.0.

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
Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project. 
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
Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project.
name string yes The name of the tag or wildcard. 
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

History
  • deploy_key_id configuration introduced in GitLab 17.5.

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"
}'
Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project.
name string yes The name of the tag or wildcard.
allowed_to_create array no Array 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_level string no Access levels allowed to create. Default: 40, for Maintainer role.

Example response: 

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

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"
Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project.
name string yes The name of the tag.