Group-level Variables API
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
Use this API to interact with CI/CD variables for a group.
List group variables
Get list of a group’s variables. Use the page and per_page pagination parameters to control the pagination of results.
GET /groups/:id/variables| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | The ID of a group or URL-encoded path of the group |
curl \ --header "PRIVATE-TOKEN: <your_access_token>" \ --url "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 or 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>" \ --url "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 or 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>" \ --url "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 or 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>" \ --url "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 or 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>" \ --url "https://gitlab.example.com/api/v4/groups/1/variables/VARIABLE_1"The filter parameter
- Tier: Premium, Ultimate
- Offering: GitLab.com, GitLab 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>" \ --url "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>" \ --url "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>" \ --url "https://gitlab.example.com/api/v4/groups/1/variables/SCOPED_VARIABLE_1?filter[environment_scope]=production"