Project-level CI/CD 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 project.
List project variables
Get list of a project’s variables. Use the page and per_page pagination parameters to control the pagination of results.
GET /projects/:id/variables| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | ID or URL-encoded path of the project |
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables"Example response:
[ { "variable_type": "env_var", "key": "TEST_VARIABLE_1", "value": "TEST_1", "protected": false, "masked": true, "hidden": false, "raw": false, "environment_scope": "*", "description": null }, { "variable_type": "env_var", "key": "TEST_VARIABLE_2", "value": "TEST_2", "protected": false, "masked": false, "hidden": false, "raw": false, "environment_scope": "*", "description": null } ]Get a single variable
Get the details of a single variable. If there are multiple variables with the same key, use filter to select the correct environment_scope.
GET /projects/:id/variables/:key| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | ID or URL-encoded path of the project |
key | string | Yes | The key of a variable |
filter | hash | No | Available filters: [environment_scope]. See the filter parameter details. |
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/TEST_VARIABLE_1"Example response:
{ "key": "TEST_VARIABLE_1", "variable_type": "env_var", "value": "TEST_1", "protected": false, "masked": true, "hidden": false, "raw": false, "environment_scope": "*", "description": null }Create a variable
Create a new variable. If a variable with the same key already exists, the new variable must have a different environment_scope. Otherwise, GitLab returns a message similar to: VARIABLE_NAME has already been taken.
POST /projects/:id/variables| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | ID or URL-encoded path of the project |
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. Default: null. Introduced in GitLab 16.2. |
environment_scope | string | No | The environment_scope of the variable. Default: * |
masked | boolean | No | Whether the variable is masked. Default: false |
masked_and_hidden | boolean | No | Whether the variable is masked and hidden. Default: false |
protected | boolean | No | Whether the variable is protected. Default: false |
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 |
Example request:
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ "https://gitlab.example.com/api/v4/projects/1/variables" --form "key=NEW_VARIABLE" --form "value=new value"Example response:
{ "variable_type": "env_var", "key": "NEW_VARIABLE", "value": "new value", "protected": false, "masked": false, "hidden": false, "raw": false, "environment_scope": "*", "description": null }Update a variable
Update a project’s variable. If there are multiple variables with the same key, use filter to select the correct environment_scope.
PUT /projects/:id/variables/:key| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | ID or URL-encoded path of the project |
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 the variable |
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 |
Example request:
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ "https://gitlab.example.com/api/v4/projects/1/variables/NEW_VARIABLE" --form "value=updated value"Example response:
{ "variable_type": "env_var", "key": "NEW_VARIABLE", "value": "updated value", "protected": true, "masked": false, "hidden": false, "raw": false, "environment_scope": "*", "description": "null" }Delete a variable
Delete a project’s variable. If there are multiple variables with the same key, use filter to select the correct environment_scope.
DELETE /projects/:id/variables/:key| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | ID or URL-encoded path of the project |
key | string | Yes | The key of a variable |
filter | hash | No | Available filters: [environment_scope]. See the filter parameter details. |
Example request:
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/VARIABLE_1"The filter parameter
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/projects/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/projects/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/projects/1/variables/SCOPED_VARIABLE_1?filter[environment_scope]=production"