group_level_variables.md 3.73 KB
Newer Older
Shinya Maeda's avatar
Shinya Maeda committed
1
# Group-level Variables  API
Tomasz Maczukin's avatar
Tomasz Maczukin committed
2

3 4
> [Introduced][ce-34519] in GitLab 9.5

Shinya Maeda's avatar
Shinya Maeda committed
5
## List group variables
Tomasz Maczukin's avatar
Tomasz Maczukin committed
6

Shinya Maeda's avatar
Shinya Maeda committed
7
Get list of a group's variables.
Tomasz Maczukin's avatar
Tomasz Maczukin committed
8 9

```
Shinya Maeda's avatar
Shinya Maeda committed
10
GET /groups/:id/variables
Tomasz Maczukin's avatar
Tomasz Maczukin committed
11 12
```

13 14
| Attribute | Type    | required | Description         |
|-----------|---------|----------|---------------------|
Shinya Maeda's avatar
Shinya Maeda committed
15
| `id`      | integer/string | yes      | The ID of a group or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
16 17

```
18
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables"
19
```
Tomasz Maczukin's avatar
Tomasz Maczukin committed
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35

```json
[
    {
        "key": "TEST_VARIABLE_1",
        "value": "TEST_1"
    },
    {
        "key": "TEST_VARIABLE_2",
        "value": "TEST_2"
    }
]
```

## Show variable details

Shinya Maeda's avatar
Shinya Maeda committed
36
Get the details of a group's specific variable.
Tomasz Maczukin's avatar
Tomasz Maczukin committed
37 38

```
Shinya Maeda's avatar
Shinya Maeda committed
39
GET /groups/:id/variables/:key
Tomasz Maczukin's avatar
Tomasz Maczukin committed
40 41
```

42 43
| Attribute | Type    | required | Description           |
|-----------|---------|----------|-----------------------|
Shinya Maeda's avatar
Shinya Maeda committed
44
| `id`      | integer/string | yes      | The ID of a group or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user   |
45
| `key`     | string  | yes      | The `key` of a variable |
46 47

```
48
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables/TEST_VARIABLE_1"
49 50
```

Tomasz Maczukin's avatar
Tomasz Maczukin committed
51 52 53 54 55 56 57 58 59
```json
{
    "key": "TEST_VARIABLE_1",
    "value": "TEST_1"
}
```

## Create variable

Shinya Maeda's avatar
Shinya Maeda committed
60
Create a new variable.
Tomasz Maczukin's avatar
Tomasz Maczukin committed
61 62

```
Shinya Maeda's avatar
Shinya Maeda committed
63
POST /groups/:id/variables
Tomasz Maczukin's avatar
Tomasz Maczukin committed
64 65
```

66 67
| Attribute   | Type    | required | Description           |
|-------------|---------|----------|-----------------------|
Shinya Maeda's avatar
Shinya Maeda committed
68
| `id`        | integer/string | yes      | The ID of a group or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user   |
69 70 71
| `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 |
| `protected` | boolean | no       | Whether the variable is protected |
72 73

```
74
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables" --form "key=NEW_VARIABLE" --form "value=new value"
75 76
```

Tomasz Maczukin's avatar
Tomasz Maczukin committed
77 78 79
```json
{
    "key": "NEW_VARIABLE",
80 81
    "value": "new value",
    "protected": false
Tomasz Maczukin's avatar
Tomasz Maczukin committed
82 83 84 85 86
}
```

## Update variable

Shinya Maeda's avatar
Shinya Maeda committed
87
Update a group's variable.
Tomasz Maczukin's avatar
Tomasz Maczukin committed
88 89

```
Shinya Maeda's avatar
Shinya Maeda committed
90
PUT /groups/:id/variables/:key
Tomasz Maczukin's avatar
Tomasz Maczukin committed
91 92
```

93 94
| Attribute   | Type    | required | Description             |
|-------------|---------|----------|-------------------------|
Shinya Maeda's avatar
Shinya Maeda committed
95
| `id`        | integer/string | yes      | The ID of a group or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user     |
96 97 98
| `key`       | string  | yes      | The `key` of a variable   |
| `value`     | string  | yes      | The `value` of a variable |
| `protected` | boolean | no       | Whether the variable is protected |
99 100

```
101
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables/NEW_VARIABLE" --form "value=updated value"
102 103
```

Tomasz Maczukin's avatar
Tomasz Maczukin committed
104 105 106
```json
{
    "key": "NEW_VARIABLE",
107 108
    "value": "updated value",
    "protected": true
Tomasz Maczukin's avatar
Tomasz Maczukin committed
109 110 111 112 113
}
```

## Remove variable

Shinya Maeda's avatar
Shinya Maeda committed
114
Remove a group's variable.
Tomasz Maczukin's avatar
Tomasz Maczukin committed
115 116

```
Shinya Maeda's avatar
Shinya Maeda committed
117
DELETE /groups/:id/variables/:key
Tomasz Maczukin's avatar
Tomasz Maczukin committed
118 119
```

120 121
| Attribute | Type    | required | Description             |
|-----------|---------|----------|-------------------------|
Shinya Maeda's avatar
Shinya Maeda committed
122
| `id`      | integer/string | yes      | The ID of a group or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user     |
123
| `key`     | string  | yes      | The `key` of a variable |
124 125

```
126
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables/VARIABLE_1"
127
```
128 129

[ce-34519]: https://gitlab.com/gitlab-org/gitlab-ce/issues/34519