1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
---
stage: Verify
group: Pipeline Authoring
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# Instance-level CI/CD variables API
DETAILS:
**Tier:** Free, Premium, Ultimate
**Offering:** Self-managed, GitLab Dedicated
## List all instance variables
> - `description` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418331) in GitLab 16.8.
Get the list of all instance-level variables.
```plaintext
GET /admin/ci/variables
```
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/admin/ci/variables"
```
```json
[
{
"key": "TEST_VARIABLE_1",
"description": null,
"variable_type": "env_var",
"value": "TEST_1",
"protected": false,
"masked": false,
"raw": false
},
{
"key": "TEST_VARIABLE_2",
"description": null,
"variable_type": "env_var",
"value": "TEST_2",
"protected": false,
"masked": false,
"raw": false
}
]
```
## Show instance variable details
> - `description` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418331) in GitLab 16.8.
Get the details of a specific instance-level variable.
```plaintext
GET /admin/ci/variables/:key
```
| Attribute | Type | Required | Description |
|-----------|---------|----------|-------------|
| `key` | string | Yes | The `key` of a variable |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/admin/ci/variables/TEST_VARIABLE_1"
```
```json
{
"key": "TEST_VARIABLE_1",
"description": null,
"variable_type": "env_var",
"value": "TEST_1",
"protected": false,
"masked": false,
"raw": false
}
```
## Create instance variable
> - `description` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418331) in GitLab 16.8.
Create a new instance-level variable.
The [maximum number of instance-level variables](../administration/instance_limits.md#cicd-variable-limits) can be changed.
```plaintext
POST /admin/ci/variables
```
| Attribute | Type | Required | Description |
|-----------------|---------|----------|-------------|
| `key` | string | Yes | The `key` of the variable. Maximum of 255 characters, only `A-Z`, `a-z`, `0-9`, and `_` are allowed. |
| `value` | string | Yes | The `value` of the variable. Maximum of 10,000 characters. |
| `description` | string | No | The description of the variable. Maximum of 255 characters. |
| `masked` | boolean | No | Whether the variable is masked. |
| `protected` | boolean | No | Whether the variable is protected. |
| `raw` | boolean | No | Whether the variable is expandable. |
| `variable_type` | string | No | The type of the variable. Available types are: `env_var` (default) and `file`. |
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/admin/ci/variables" --form "key=NEW_VARIABLE" --form "value=new value"
```
```json
{
"key": "NEW_VARIABLE",
"description": null,
"value": "new value",
"variable_type": "env_var",
"protected": false,
"masked": false,
"raw": false
}
```
## Update instance variable
> - `description` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418331) in GitLab 16.8.
Update an instance-level variable.
```plaintext
PUT /admin/ci/variables/:key
```
| Attribute | Type | Required | Description |
|-----------------|---------|----------|-------------|
| `description` | string | No | The description of the variable. Maximum of 255 characters. |
| `key` | string | Yes | The `key` of the variable. Maximum of 255 characters, only `A-Z`, `a-z`, `0-9`, and `_` are allowed. |
| `masked` | boolean | No | Whether the variable is masked. |
| `protected` | boolean | No | Whether the variable is protected. |
| `raw` | boolean | No | Whether the variable is expandable. |
| `value` | string | Yes | The `value` of the variable. Maximum of 10,000 characters. |
| `variable_type` | string | No | The type of the variable. Available types are: `env_var` (default) and `file`. |
```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/admin/ci/variables/NEW_VARIABLE" --form "value=updated value"
```
```json
{
"key": "NEW_VARIABLE",
"description": null,
"value": "updated value",
"variable_type": "env_var",
"protected": true,
"masked": true,
"raw": true
}
```
## Remove instance variable
Remove an instance-level variable.
```plaintext
DELETE /admin/ci/variables/:key
```
| Attribute | Type | Required | Description |
|-----------|--------|----------|-------------|
| `key` | string | Yes | The `key` of a variable |
```shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/admin/ci/variables/VARIABLE_1"
```
|
