CI variables

Use this API to manage CI/CD variables for a project, a group, or an instance.

Managing project variables requires the Maintainer role for the project. Managing group variables requires the Owner role for the group. Managing instance variables requires administrator access.

List all instance variables

GET /api/v4/admin/ci/variables

Lists all instance-level variables. Use the page and per_page pagination parameters to control the pagination of results.

Parameters

Name	Type	Description
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCiVariable
`400`	Bad Request	—

Create a new instance-level variable

POST /api/v4/admin/ci/variables

FE version

Request body (application/json)

Property	Type	Description
`description`	String	The description of the variable
`key` Required	String	The key of the variable. Max 255 characters
`masked`	Boolean	Whether the variable is masked
`protected`	Boolean	Whether the variable is protected
`raw`	Boolean	Whether the variable will be expanded
`value` Required	String	The value of a variable
`variable_type`	String	The type of a variable. Available types are: env_var (default) and file Allowed values: `env_var`, `file`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesCiVariable
`400`	400 Bad Request	—

Retrieve instance variable details

GET /api/v4/admin/ci/variables/{key}

Retrieves details of a specified instance-level variable.

Parameters

Name	Type	Description
`key` Path, required	String	Key of the instance variable. Must be 255 characters or fewer and contain only `A-Z`, `a-z`, `0-9`, and `_`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCiVariable
`400`	Bad Request	—
`404`	Instance Variable Not Found	—

Update an instance-level variable

PUT /api/v4/admin/ci/variables/{key}

FE version

Parameters

Name	Type	Description
`key` Path, required	String	The key of a variable

Request body (application/json)

Property	Type	Description
`description`	String	The description of the variable
`masked`	Boolean	Whether the variable is masked
`protected`	Boolean	Whether the variable is protected
`raw`	Boolean	Whether the variable will be expanded
`value`	String	The value of a variable
`variable_type`	String	The type of a variable. Available types are: env_var (default) and file Allowed values: `env_var`, `file`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCiVariable
`400`	Bad Request	—
`404`	Instance Variable Not Found	—

Delete an existing instance-level variable

DELETE /api/v4/admin/ci/variables/{key}

FE version

Parameters

Name	Type	Description
`key` Path, required	String	The key of a variable

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCiVariable
`400`	Bad Request	—
`404`	Instance Variable Not Found	—

List all group variables

GET /api/v4/groups/{id}/variables

Lists all variables for a specified group. Use the page and per_page pagination parameters to control the pagination of results.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the group
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCiVariable
`400`	Bad Request	—
`404`	Not Found	—

Create a group variable

POST /api/v4/groups/{id}/variables

Creates a group variable.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the group

Request body (application/json)

Property	Type	Description
`description`	String	Description of the variable. Limited to 255 characters
`environment_scope`	String	The environment scope of a variable
`key` Required	String	Key of the group variable. Must be 255 characters or fewer and contain only `A-Z`, `a-z`, `0-9`, and `_`
`masked`	Boolean	If `true`, the variable is masked
`masked_and_hidden`	Boolean	If `true`, the variable is masked and hidden
`protected`	Boolean	If `true`, the variable is protected
`raw`	Boolean	If `true`, the variable is treated as a raw string. If `false`, the value is expanded
`value` Required	String	Value of the variable
`variable_type`	String	The type of the variable Allowed values: `env_var`, `file` Default: `env_var`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesCiVariable
`400`	400 Bad Request	—
`404`	Not Found	—

Retrieve details of a group variable

GET /api/v4/groups/{id}/variables/{key}

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

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the group
`key` Path, required	String	Key of the group variable. Must be 255 characters or fewer and contain only `A-Z`, `a-z`, `0-9`, and `_`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCiVariable
`400`	Bad Request	—
`404`	Group Variable Not Found	—

Update a group variable

PUT /api/v4/groups/{id}/variables/{key}

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

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the group
`key` Path, required	String	Key of the group variable. Must be 255 characters or fewer and contain only `A-Z`, `a-z`, `0-9`, and `_`

Request body (application/json)

Property	Type	Description
`description`	String	Description of the variable. Limited to 255 characters
`environment_scope`	String	The environment scope of a variable
`masked`	Boolean	If `true`, the variable is masked
`protected`	Boolean	If `true`, the variable is protected
`raw`	Boolean	If `true`, the variable is treated as a raw string. If `false`, the value is expanded
`value`	String	Value of the variable
`variable_type`	String	The type of the variable. Default: env_var Allowed values: `env_var`, `file`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCiVariable
`400`	400 Bad Request	—
`404`	Group Variable Not Found	—

Delete a group variable

DELETE /api/v4/groups/{id}/variables/{key}

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

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the group
`key` Path, required	String	Key of the group variable. Must be 255 characters or fewer and contain only `A-Z`, `a-z`, `0-9`, and `_`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCiVariable
`400`	Bad Request	—
`404`	Group Variable Not Found	—

List all project variables

GET /api/v4/projects/{id}/variables

Lists all variables for a project. Use the page and per_page pagination parameters to control the pagination of results.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCiVariable
`400`	Bad Request	—
`404`	Not Found	—

Create a variable

POST /api/v4/projects/{id}/variables

Creates a variable. If a variable with the same key already exists, the variable must have a different environment_scope. Otherwise, GitLab returns a message similar to: VARIABLE_NAME has already been taken.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project

Request body (application/json)

Property	Type	Description
`description`	String	Description of the variable. Limited to 255 characters
`environment_scope`	String	Environment scope of the variable. Defaults to `*`
`key` Required	String	Key of the project variable. Must be 255 characters or fewer and contain only `A-Z`, `a-z`, `0-9`, and `_`
`masked`	Boolean	If `true`, the variable is masked
`masked_and_hidden`	Boolean	If `true`, the variable is masked and hidden. Introduced in GitLab 17.4
`protected`	Boolean	If `true`, the variable is protected
`raw`	Boolean	If `true`, the variable is treated as a raw string. If `false`, the value is expanded
`value` Required	String	Value of the variable
`variable_type`	String	The type of the variable Allowed values: `env_var`, `file` Default: `env_var`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesCiVariable
`400`	400 Bad Request	—
`404`	Not Found	—

Retrieve a single variable

GET /api/v4/projects/{id}/variables/{key}

Retrieves details of a specified variable. If there are multiple variables with the same key, use filter to select the correct environment_scope.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`key` Path, required	String	Key of the project variable. Must be 255 characters or fewer and contain only `A-Z`, `a-z`, `0-9`, and `_`
`filter` Query	Object	Filter results when multiple variables share the same key
`filter[environment_scope]` Query	String	Environment scope of the variable

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCiVariable
`400`	Bad Request	—
`404`	Variable Not Found	—

Update a variable

PUT /api/v4/projects/{id}/variables/{key}

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

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`key` Path, required	String	Key of the project variable. Must be 255 characters or fewer and contain only `A-Z`, `a-z`, `0-9`, and `_`

Request body (application/json)

Property	Type	Description
`description`	String	Description of the variable. Limited to 255 characters
`environment_scope`	String	Environment scope of the variable
`filter`	Object	Filter results when multiple variables share the same key
`filter.environment_scope`	String	Environment scope of the variable
`masked`	Boolean	If `true`, the variable is masked
`protected`	Boolean	If `true`, the variable is protected
`raw`	Boolean	If `true`, the variable is treated as a raw string. If `false`, the value is expanded
`value`	String	Value of the variable
`variable_type`	String	The type of the variable. Default: env_var Allowed values: `env_var`, `file`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCiVariable
`400`	Bad Request	—
`404`	Variable Not Found	—

Delete a variable

DELETE /api/v4/projects/{id}/variables/{key}

Deletes a project variable. If there are multiple variables with the same key, use filter to select the correct environment_scope.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`key` Path, required	String	Key of the project variable. Must be 255 characters or fewer and contain only `A-Z`, `a-z`, `0-9`, and `_`
`filter` Query	Object	Filter results when multiple variables share the same key
`filter[environment_scope]` Query	String	Environment scope of the variable

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCiVariable
`400`	Bad Request	—
`404`	Variable Not Found	—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesCiVariable

Property	Type	Description
`description`	String	Example: `This variable is being used for ...`
`environment_scope`	String	Example: `*`
`hidden`	Boolean	—
`key`	String	Example: `TEST_VARIABLE_1`
`masked`	Boolean	—
`protected`	Boolean	—
`raw`	Boolean	—
`value`	String	Example: `TEST_1`
`variable_type`	String	Example: `env_var`

List all instance variables

Create a new instance-level variable

Retrieve instance variable details

Update an instance-level variable

Delete an existing instance-level variable

List all group variables

Create a group variable

Retrieve details of a group variable

Update a group variable

Delete a group variable

List all project variables

Create a variable

Retrieve a single variable

Update a variable

Delete a variable

Schemas

APIEntitiesCiVariable

Request trial access

Thank you

Error

Request callback

Thank you

Something went wrong

Book your sessions

Thank you

Error

Request demo

Thank you

Error

Get the PCI SSC compliance report

Thank you

Error

Request partner program details

Request received

Error