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 access30
: Developer role40
: 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
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
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"
}
]
}
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 ID1
for user with ID10
.create_access_levels
with ID2
for group with ID20
.
{
"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"
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. |
Related topics
- Tags API for all tags
- Tags user documentation
- Protected tags user documentation
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support