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 all group variables
Lists all variables for a specified group. 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 --request GET \ --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 } ]Retrieve details of a group variable
Retrieves details of a specified group 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 | ID of a group or URL-encoded path of the group. |
key | string | Yes | Key of a variable. |
filter | hash | No | Filters results when multiple variables share the same key. Possible values: [environment_scope]. Premium and Ultimate only. |
curl --request GET \ --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/groups/1/variables/SCOPED_VARIABLE_1?filter[environment_scope]=production"{ "key": "TEST_VARIABLE_1", "variable_type": "env_var", "value": "TEST_1", "protected": false, "masked": false, "hidden": false, "raw": false, "environment_scope": "*", "description": null }Create a group variable
Creates a group 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: true. When false, variables in the value are 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 a group variable
Updates the specified group variable. If there are multiple variables with the same key, use filter to select the correct environment_scope.
When filtering for an environment_scope that does not exist, the endpoint falls back to updating a variable with the same name but different environment scope. Verify the existence of a scope for a given variable using the retrieve details of a group variable endpoint.
PUT /groups/:id/variables/:key| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | ID of a group or URL-encoded path of the group. |
key | string | Yes | Key of a variable. |
value | string | Yes | Value of a variable. |
description | string | No | Description of the variable. Introduced in GitLab 16.2. Default: null. |
environment_scope | string | No | Environment scope of a variable. Premium and Ultimate only. |
filter | hash | No | Filters results when multiple variables share the same key. Possible values: [environment_scope]. Premium and Ultimate only. |
masked | boolean | No | If true, indicates the variable is masked. |
protected | boolean | No | If true, indicates the variable is protected. |
raw | boolean | No | If true, indicates the variable is treated as a raw string. When false, the variable value is expanded. Default: true. |
variable_type | string | No | 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/SCOPED_VARIABLE_1?value=scoped-variable-updated-value&environment_scope=production&filter[environment_scope]=production" \ --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 }Delete a group variable
Deletes the specified group 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 | ID of a group or URL-encoded path of the group. |
key | string | Yes | Key of a variable. |
filter | hash | No | Filters results when multiple variables share the same key. Possible values: [environment_scope]. Premium and Ultimate only. |
curl --request DELETE \ --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/groups/1/variables/SCOPED_VARIABLE_1?filter[environment_scope]=production"