Group-level Variables API

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Version history

Introduced filter in GitLab 16.9.

Use this API to interact with CI/CD variables for a group.

Prerequisites:

You must have the Owner role for the 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

Version history

The filter parameter was introduced in GitLab 16.9.

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.

Example request:

curl --request GET \
  --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
}

Example request with filter:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/variables/SCOPED_VARIABLE_1" \
  --form "filter[environment_scope]=production"

Create a group variable

Version history

masked_and_hidden and hidden attributes introduced in GitLab 17.4.

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. Maximum 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. Maximum 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

Version history

The filter parameter was introduced in GitLab 16.9.

Updates the specified group variable. If there are multiple variables with the same key, use filter to select the correct environment_scope.

Warning

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`.

Example request:

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
}

Example request with filter:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/variables/SCOPED_VARIABLE_1" \
  --form "value=updated value" \
  --form "environment_scope=production" \
  --form "filter[environment_scope]=production"

Delete a group variable

Version history

The filter parameter was introduced in GitLab 16.9.

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.

Example request:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/variables/VARIABLE_1"

Example request with filter:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/variables/SCOPED_VARIABLE_1" \
  --form "filter[environment_scope]=production"