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	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items 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	The key of a variable

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	The ID of a group or URL-encoded path of the group owned by the authenticated user
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items 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	The ID of a group or URL-encoded path of the group owned by the authenticated user

Request body (application/json)

Property	Type	Description
`description`	String	The description of the variable
`environment_scope`	String	The environment scope of a variable
`key` Required	String	The ID of a group or URL-encoded path of the group owned by the authenticated user
`masked`	Boolean	Whether the variable is masked
`masked_and_hidden`	Boolean	Whether the variable is masked and hidden
`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 the variable. Default: env_var Allowed values: `env_var`, `file`

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	The ID of a group or URL-encoded path of the group owned by the authenticated user
`key` Path, required	String	The key of the variable

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	The ID of a group or URL-encoded path of the group owned by the authenticated user
`key` Path, required	String	The key of a variable

Request body (application/json)

Property	Type	Description
`description`	String	The description of the variable
`environment_scope`	String	The environment scope of a 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 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	The ID of a group or URL-encoded path of the group owned by the authenticated user
`key` Path, required	String	The key of a variable

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	The ID of a project or URL-encoded NAMESPACE/PROJECT_NAME of the project owned by the authenticated user
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items 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	The ID of a project or URL-encoded NAMESPACE/PROJECT_NAME of the project owned by the authenticated user

Request body (application/json)

Property	Type	Description
`description`	String	The description of the variable
`environment_scope`	String	The environment_scope of the variable
`key` Required	String	The key of a variable
`masked`	Boolean	Whether the variable is masked
`masked_and_hidden`	Boolean	Whether the variable is masked and hidden
`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 the variable. Default: env_var Allowed values: `env_var`, `file`

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	The ID of a project or URL-encoded NAMESPACE/PROJECT_NAME of the project owned by the authenticated user
`key` Path, required	String	The key of a variable
`filter` Query	Object	Available filters: [environment_scope]. Example: filter[environment_scope]=production
`filter[environment_scope]` Query	String	The environment scope of a 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	The ID of a project or URL-encoded NAMESPACE/PROJECT_NAME of the project owned by the authenticated user
`key` Path, required	String	The key of a variable

Request body (application/json)

Property	Type	Description
`description`	String	The description of the variable
`environment_scope`	String	The environment_scope of a variable
`filter`	Object	Available filters: [environment_scope]. Example: filter[environment_scope]=production
`filter.environment_scope`	String	The environment scope of a 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 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	The ID of a project or URL-encoded NAMESPACE/PROJECT_NAME of the project owned by the authenticated user
`key` Path, required	String	The key of a variable
`filter` Query	Object	Available filters: [environment_scope]. Example: filter[environment_scope]=production
`filter[environment_scope]` Query	String	The 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