Group-level Variables API
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, Self-managed, GitLab Dedicated
List group variables
Get list of a group’s variables.
GET /groups/:id/variables
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | Yes | The ID of a group or URL-encoded path of the group |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables"
[
{
"key": "TEST_VARIABLE_1",
"variable_type": "env_var",
"value": "TEST_1",
"protected": false,
"masked": false,
"hidden": false,
"raw": false,
"environment_scope": "*",
"description": null
},
{
"key": "TEST_VARIABLE_2",
"variable_type": "env_var",
"value": "TEST_2",
"protected": false,
"masked": false,
"hidden": false,
"raw": false,
"environment_scope": "*",
"description": null
}
]
Show variable details
Get the details of a group’s specific variable. If there are multiple variables with the same key,
use filter
to select the correct environment_scope
.
GET /groups/:id/variables/:key
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | Yes | The ID of a group or URL-encoded path of the group |
key |
string | Yes | The key of a variable |
filter |
hash | No | Available filters: [environment_scope] . See the filter parameter details. |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables/TEST_VARIABLE_1"
{
"key": "TEST_VARIABLE_1",
"variable_type": "env_var",
"value": "TEST_1",
"protected": false,
"masked": false,
"hidden": false,
"raw": false,
"environment_scope": "*",
"description": null
}
Create variable
Create a new variable.
POST /groups/:id/variables
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | Yes | The ID of a group or URL-encoded path of the group. |
key |
string | Yes | The key of a variable; must have no more than 255 characters; only A-Z , a-z , 0-9 , and _ are allowed. |
value |
string | Yes | The value of a variable. |
description |
string | No | The description of the variable; must have no more than 255 characters. Default: null . |
environment_scope |
string | No | The environment scope of a variable. Premium and Ultimate only. |
masked |
boolean | No | Whether the variable is masked. |
masked_and_hidden |
boolean | No | Whether the variable is masked and hidden. Default: false |
protected |
boolean | No | Whether the variable is protected. |
raw |
boolean | No | Whether the variable is treated as a raw string. Default: false . When true , variables in the value are not expanded. |
variable_type |
string | No | The type of a variable. Available types are: env_var (default) and file . |
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/groups/1/variables" --form "key=NEW_VARIABLE" --form "value=new value"
{
"key": "NEW_VARIABLE",
"value": "new value",
"variable_type": "env_var",
"protected": false,
"masked": false,
"hidden": false,
"raw": false,
"environment_scope": "*",
"description": null
}
Update variable
Update a group’s variable. If there are multiple variables with the same key,
use filter
to select the correct environment_scope
.
PUT /groups/:id/variables/:key
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | Yes | The ID of a group or URL-encoded path of the group |
key |
string | Yes | The key of a variable |
value |
string | Yes | The value of a variable |
description |
string | No | The description of the variable. Default: null . Introduced in GitLab 16.2. |
environment_scope |
string | No | The environment scope of a variable. Premium and Ultimate only. |
filter |
hash | No | Available filters: [environment_scope] . See the filter parameter details. |
masked |
boolean | No | Whether the variable is masked |
protected |
boolean | No | Whether the variable is protected |
raw |
boolean | No | Whether the variable is treated as a raw string. Default: false . When true , variables in the value are not expanded. |
variable_type |
string | No | The type of a variable. Available types are: env_var (default) and file |
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/groups/1/variables/NEW_VARIABLE" --form "value=updated value"
{
"key": "NEW_VARIABLE",
"value": "updated value",
"variable_type": "env_var",
"protected": true,
"masked": true,
"hidden": false,
"raw": true,
"environment_scope": "*",
"description": null
}
Remove variable
Remove a group’s variable. If there are multiple variables with the same key,
use filter
to select the correct environment_scope
.
DELETE /groups/:id/variables/:key
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | Yes | The ID of a group or URL-encoded path of the group |
key |
string | Yes | The key of a variable |
filter |
hash | No | Available filters: [environment_scope] . See the filter parameter details. |
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/groups/1/variables/VARIABLE_1"
The filter
parameter
- Tier: Premium, Ultimate
- Offering: GitLab.com, Self-managed, GitLab Dedicated
When multiple variables have the same key
, GET, PUT,
or DELETE requests might return:
There are multiple variables with provided parameters. Please use 'filter[environment_scope]'.
Use filter[environment_scope]
to select the variable with the matching environment_scope
attribute.
For example:
-
GET:
curl --globoff --header "PRIVATE-TOKEN: <your_access_token>" \ "https://gitlab.example.com/api/v4/groups/1/variables/SCOPED_VARIABLE_1?filter[environment_scope]=production"
-
PUT:
curl --request PUT --globoff --header "PRIVATE-TOKEN: <your_access_token>" \ "https://gitlab.example.com/api/v4/groups/1/variables/SCOPED_VARIABLE_1?value=scoped-variable-updated-value&environment_scope=production&filter[environment_scope]=production"
-
DELETE:
curl --request DELETE --globoff --header "PRIVATE-TOKEN: <your_access_token>" \ "https://gitlab.example.com/api/v4/groups/1/variables/SCOPED_VARIABLE_1?filter[environment_scope]=production"
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