diff options
Diffstat (limited to 'doc/api/group_level_variables.md')
| -rw-r--r-- | doc/api/group_level_variables.md | 96 |
1 files changed, 72 insertions, 24 deletions
diff --git a/doc/api/group_level_variables.md b/doc/api/group_level_variables.md index 109f3ba5f6e..aeab76b7212 100644 --- a/doc/api/group_level_variables.md +++ b/doc/api/group_level_variables.md @@ -49,7 +49,10 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a ## Show variable details -Get the details of a group's specific variable. +> The `filter` parameter was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340185) in GitLab 16.9. + +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`. ```plaintext GET /groups/:id/variables/:key @@ -59,6 +62,7 @@ GET /groups/:id/variables/:key |-----------|----------------|----------|-------------| | `id` | integer/string | Yes | The ID of a group or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `key` | string | Yes | The `key` of a variable | +| `filter` | hash | No | Available filters: `[environment_scope]`. See the [`filter` parameter details](#the-filter-parameter). | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables/TEST_VARIABLE_1" @@ -85,17 +89,17 @@ 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](rest/index.md#namespaced-path-encoding) | -| `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 | -| `variable_type` | string | No | The type of a variable. Available types are: `env_var` (default) and `file` | -| `protected` | boolean | No | Whether the variable is protected | -| `masked` | boolean | No | Whether the variable is masked | -| `raw` | boolean | No | Whether the variable is treated as a raw string. Default: `false`. When `true`, variables in the value are not [expanded](../ci/variables/index.md#prevent-cicd-variable-expansion). | +| Attribute | Type | Required | Description | +|---------------------------------------|----------------|----------|-------------| +| `id` | integer/string | Yes | The ID of a group or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | +| `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` | | `environment_scope` **(PREMIUM ALL)** | string | No | The [environment scope](../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable) of a variable | -| `description` | string | No | The `description` of the variable. Default: `null` | +| `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](../ci/variables/index.md#prevent-cicd-variable-expansion). | +| `variable_type` | string | No | The type of a variable. Available types are: `env_var` (default) and `file` | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ @@ -117,23 +121,27 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ ## Update variable -Update a group's variable. +> The `filter` parameter was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340185) in GitLab 16.9. + +Update a group's variable. If there are multiple variables with the same key, +use `filter` to select the correct `environment_scope`. ```plaintext 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](rest/index.md#namespaced-path-encoding) | -| `key` | string | Yes | The `key` of a variable | -| `value` | string | Yes | The `value` of a variable | -| `variable_type` | string | No | The type of a variable. Available types are: `env_var` (default) and `file` | -| `protected` | boolean | No | Whether the variable is protected | -| `masked` | boolean | No | Whether the variable is masked | -| `raw` | boolean | No | Whether the variable is treated as a raw string. Default: `false`. When `true`, variables in the value are not [expanded](../ci/variables/index.md#prevent-cicd-variable-expansion). | +| Attribute | Type | Required | Description | +|---------------------------------------|----------------|----------|-------------| +| `id` | integer/string | Yes | The ID of a group or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | +| `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](https://gitlab.com/gitlab-org/gitlab/-/issues/409641) in GitLab 16.2. | | `environment_scope` **(PREMIUM ALL)** | string | No | The [environment scope](../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable) of a variable | -| `description` | string | No | The description of the variable. Default: `null`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/409641) in GitLab 16.2. | +| `filter` | hash | No | Available filters: `[environment_scope]`. See the [`filter` parameter details](#the-filter-parameter). | +| `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](../ci/variables/index.md#prevent-cicd-variable-expansion). | +| `variable_type` | string | No | The type of a variable. Available types are: `env_var` (default) and `file` | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ @@ -155,7 +163,10 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ ## Remove variable -Remove a group's variable. +> The `filter` parameter was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340185) in GitLab 16.9. + +Remove a group's variable. If there are multiple variables with the same key, +use `filter` to select the correct `environment_scope`. ```plaintext DELETE /groups/:id/variables/:key @@ -163,10 +174,47 @@ 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](rest/index.md#namespaced-path-encoding) | +| `id` | integer/string | Yes | The ID of a group or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `key` | string | Yes | The `key` of a variable | +| `filter` | hash | No | Available filters: `[environment_scope]`. See the [`filter` parameter details](#the-filter-parameter). | ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \ "https://gitlab.example.com/api/v4/groups/1/variables/VARIABLE_1" ``` + +## The `filter` parameter **(PREMIUM ALL)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340185) in GitLab 16.9. + +When multiple variables have the same `key`, [GET](#show-variable-details), [PUT](#update-variable), +or [DELETE](#remove-variable) requests might return: + +```plaintext +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: + + ```shell + 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: + + ```shell + 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: + + ```shell + 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" + ``` |