CI/CD variables

CI/CD variables at the three scopes GitLab keeps them: a project, a group and the instance, each with the same five operations. A variable can be protected, masked or masked and hidden, and project and group variables can be scoped to an environment, so one key can hold a different value per environment. Instance variables need an administrator, and deleting a variable cannot be undone.

Sample questions

• “List the CI/CD variables of project 42”
• “Add a masked DEPLOY_TOKEN variable scoped to production”
• “Which group variables does group platform define?”

How to call it

• Dynamic, the default surface: call gitlab_execute_action with action set to the action’s ID, such as ci_variable.create, and its parameters in params. gitlab_find_action finds an ID from a description of the task.
• Meta (GITLAB_MCP_TOOL_SURFACE=meta): call gitlab_ci_variable with action set to the action’s name, such as create, and its parameters in params.
• Individual (GITLAB_MCP_TOOL_SURFACE=individual): call the action’s own tool, such as gitlab_ci_variable_create, with its parameters as the arguments.

Availability

Every tier serves the whole group, on self-managed instances and on GitLab.com alike.

Read-only actions: 6 of 15, the ones a deployment in read-only mode keeps. A token with read_api and not api is served 6 of the 15.

Actions

The description of each action, and of each of its parameters, is the text the server serves for it on the default surface, quoted as served. The token lines say what GitLab 19.4.1 requires of a token for the requests each action sends; on an instance with Admin Mode turned on, an action only an administrator may run also needs admin_mode. A destructive action runs only once confirmed, unless GITLAB_MCP_YOLO_MODE (or AUTOPILOT) skips that step: the dynamic surface needs confirm: true on gitlab_execute_action, and the other two take a confirm parameter or the client’s prompt (Destructive actions).

Action	Individual
ci_variable.create	gitlab_ci_variable_create
ci_variable.delete	gitlab_ci_variable_delete
ci_variable.get	gitlab_ci_variable_get
ci_variable.group_create	gitlab_group_variable_create
ci_variable.group_delete	gitlab_group_variable_delete
ci_variable.group_get	gitlab_group_variable_get
ci_variable.group_list	gitlab_group_variable_list
ci_variable.group_update	gitlab_group_variable_update
ci_variable.instance_create	gitlab_instance_variable_create
ci_variable.instance_delete	gitlab_instance_variable_delete
ci_variable.instance_get	gitlab_instance_variable_get
ci_variable.instance_list	gitlab_instance_variable_list
ci_variable.instance_update	gitlab_instance_variable_update
ci_variable.list	gitlab_ci_variable_list
ci_variable.update	gitlab_ci_variable_update

ci_variable.create

Create a CI/CD variable in a project with type, environment scope, and protected/masked/raw/masked_and_hidden flags. Returns: the created variable’s key, value (redacted when masked or hidden), type, flags, environment scope, and description. See also: ci_variable.list, ci_variable.get, ci_variable.update.

• Meta-tool: gitlab_ci_variable, action create
• Individual tool: gitlab_ci_variable_create
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Variable: Create at project (permissions page)
• Behavior: writes, not idempotent

Parameter	Type	Mandatory	Description
key	string	yes	Variable key name
project_id	string/integer	yes	Project ID or URL-encoded path
value	string	yes	Variable value
description	string	no	Variable description
environment_scope	string	no	Environment scope (default: *)
masked	boolean	no	Mask variable value in job logs
masked_and_hidden	boolean	no	Mask and hide variable value
protected	boolean	no	Only expose in protected branches/tags
raw	boolean	no	Treat variable value as raw string
variable_type	string (env_var, file)	no	Variable type: env_var or file

ci_variable.delete

Delete a CI/CD variable by key, selecting an environment-scoped instance via the filter. Returns: a success confirmation message. See also: ci_variable.list, ci_variable.get.

• Meta-tool: gitlab_ci_variable, action delete
• Individual tool: gitlab_ci_variable_delete
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Variable: Delete at project (permissions page)
• Behavior: writes, destructive (needs confirmation), idempotent

Parameter	Type	Mandatory	Description
key	string	yes	Variable key name
project_id	string/integer	yes	Project ID or URL-encoded path
environment_scope	string	no	Filter by environment scope (shorthand for filter.environment_scope)
filter	object	no	Filter selecting the variable by environment scope. Mirrors the GitLab variable filter object

ci_variable.get

Get a single CI/CD variable by key, optionally selecting an environment-scoped instance via the filter. Returns: the variable’s key, value (redacted when masked or hidden), type, protected/masked/hidden/raw flags, environment scope, and description. See also: ci_variable.list, ci_variable.update, ci_variable.delete.

• Meta-tool: gitlab_ci_variable, action get
• Individual tool: gitlab_ci_variable_get
• Tier: Free
• Classic or OAuth token: read_api (or api)
• Fine-grained token: Variable: Read at project (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
key	string	yes	Variable key name
project_id	string/integer	yes	Project ID or URL-encoded path
environment_scope	string	no	Filter by environment scope (shorthand for filter.environment_scope)
filter	object	no	Filter selecting the variable by environment scope. Mirrors the GitLab variable filter object

ci_variable.group_create

Create a CI/CD variable in a group with type, environment scope, and protected/masked/raw/masked_and_hidden flags. Returns: the created variable’s key, value, type, flags, environment scope, and description. See also: ci_variable.group_list, ci_variable.group_get, ci_variable.group_update.

• Meta-tool: gitlab_ci_variable, action group_create
• Individual tool: gitlab_group_variable_create
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Variable: Create at group (permissions page)
• Behavior: writes, not idempotent

Parameter	Type	Mandatory	Description
group_id	string/integer	yes	Group ID or URL-encoded path
key	string	yes	Variable key name
value	string	yes	Variable value
description	string	no	Variable description
environment_scope	string	no	Environment scope (default: *)
masked	boolean	no	Mask variable value in job logs
masked_and_hidden	boolean	no	Mask and hide variable value
protected	boolean	no	Only expose in protected branches/tags
raw	boolean	no	Treat variable value as raw string
variable_type	string (env_var, file)	no	Variable type: env_var or file

ci_variable.group_delete

Delete a group CI/CD variable by key, selecting an environment-scoped instance via the filter. Returns: a success confirmation message. See also: ci_variable.group_list, ci_variable.group_get.

• Meta-tool: gitlab_ci_variable, action group_delete
• Individual tool: gitlab_group_variable_delete
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Variable: Delete at group (permissions page)
• Behavior: writes, destructive (needs confirmation), idempotent

Parameter	Type	Mandatory	Description
group_id	string/integer	yes	Group ID or URL-encoded path
key	string	yes	Variable key name
environment_scope	string	no	Filter by environment scope (shorthand for filter.environment_scope)
filter	object	no	Filter selecting the variable by environment scope. Mirrors the GitLab variable filter object

ci_variable.group_get

Get a single group CI/CD variable by key, optionally selecting an environment-scoped instance via the filter. Returns: the variable’s key, value, type, protected/masked/hidden/raw flags, environment scope, and description. See also: ci_variable.group_list, ci_variable.group_update, ci_variable.group_delete.

• Meta-tool: gitlab_ci_variable, action group_get
• Individual tool: gitlab_group_variable_get
• Tier: Free
• Classic or OAuth token: read_api (or api)
• Fine-grained token: Variable: Read at group (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
group_id	string/integer	yes	Group ID or URL-encoded path
key	string	yes	Variable key name
environment_scope	string	no	Filter by environment scope (shorthand for filter.environment_scope)
filter	object	no	Filter selecting the variable by environment scope. Mirrors the GitLab variable filter object

ci_variable.group_list

List a group’s CI/CD variables with order_by, sort, and offset or keyset pagination. Returns: each variable’s key, value, type, protected/masked/hidden/raw flags, environment scope, description, and pagination metadata. See also: ci_variable.group_get, ci_variable.group_create, ci_variable.group_update.

• Meta-tool: gitlab_ci_variable, action group_list
• Individual tool: gitlab_group_variable_list
• Tier: Free
• Classic or OAuth token: read_api (or api)
• Fine-grained token: Variable: Read at group (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
group_id	string/integer	yes	Group ID or URL-encoded path
order_by	string	no	Column by which to order keyset-paginated results
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
page_token	string	no	Next page of a keyset listing: the next_page_token of the previous response of this action, passed back unchanged. It carries the position and every filter of the listing as GitLab read them, and those are what the next page is asked with, whatever filters are sent beside it. Leave it empty for the first page.
pagination	string	no	Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost, and a keyset page names the next one in next_page_token rather than next_page.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
sort	string (asc, desc)	no	Sort direction for keyset-paginated results (asc, desc)

ci_variable.group_update

Update a group CI/CD variable, selecting an environment-scoped instance via the filter. Returns: the updated variable’s key, value, type, protected/masked/hidden/raw flags, environment scope, and description. See also: ci_variable.group_get, ci_variable.group_list, ci_variable.group_delete.

• Meta-tool: gitlab_ci_variable, action group_update
• Individual tool: gitlab_group_variable_update
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Variable: Update at group (permissions page)
• Behavior: writes, idempotent

Parameter	Type	Mandatory	Description
group_id	string/integer	yes	Group ID or URL-encoded path
key	string	yes	Variable key name
description	string	no	Updated variable description. Pass an empty string to remove it. Omit the field to leave it untouched
environment_scope	string	no	Filter by environment scope (shorthand for filter.environment_scope)
filter	object	no	Filter selecting the variable by environment scope. Mirrors the GitLab variable filter object
masked	boolean	no	Mask variable value in job logs
protected	boolean	no	Only expose in protected branches/tags
raw	boolean	no	Treat variable value as raw string
value	string	no	Updated variable value. Pass an empty string to empty it. Omit the field to leave it untouched
variable_type	string (env_var, file)	no	Variable type: env_var or file

ci_variable.instance_create

Create an instance-level CI/CD variable with type and protected/masked/raw flags (admin-only). Returns: the created variable’s key, value (raw even when masked, because masking redacts CI job logs, not this API), type, flags, and description. See also: ci_variable.instance_list, ci_variable.instance_get, ci_variable.instance_update.

• Meta-tool: gitlab_ci_variable, action instance_create
• Individual tool: gitlab_instance_variable_create
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Variable: Create at instance (permissions page)
• Behavior: writes, not idempotent

Parameter	Type	Mandatory	Description
key	string	yes	Variable key name
value	string	yes	Variable value
description	string	no	Variable description
masked	boolean	no	Mask variable value in job logs
protected	boolean	no	Only expose in protected branches/tags
raw	boolean	no	Treat variable value as raw string
variable_type	string (env_var, file)	no	Variable type: env_var or file

ci_variable.instance_delete

Delete an instance-level CI/CD variable by key (admin-only). Returns: a success confirmation message. See also: ci_variable.instance_list, ci_variable.instance_get.

• Meta-tool: gitlab_ci_variable, action instance_delete
• Individual tool: gitlab_instance_variable_delete
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Variable: Delete at instance (permissions page)
• Behavior: writes, destructive (needs confirmation), idempotent

Parameter	Type	Mandatory	Description
key	string	yes	Variable key name

ci_variable.instance_get

Get a single instance-level CI/CD variable by key (admin-only). Returns: the variable’s key, value (raw even when masked, because masking redacts CI job logs, not this API), type, protected/masked/raw flags, and description. See also: ci_variable.instance_list, ci_variable.instance_update, ci_variable.instance_delete.

• Meta-tool: gitlab_ci_variable, action instance_get
• Individual tool: gitlab_instance_variable_get
• Tier: Free
• Classic or OAuth token: read_api (or api)
• Fine-grained token: Variable: Read at instance (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
key	string	yes	Variable key name

ci_variable.instance_list

List instance-level CI/CD variables with order_by, sort, and offset or keyset pagination (admin-only). Returns: each variable’s key, value (raw even when masked, because masking redacts CI job logs, not this API), type, protected/masked/raw flags, description, and pagination metadata. See also: ci_variable.instance_get, ci_variable.instance_create, ci_variable.instance_update, ci_variable.instance_delete.

• Meta-tool: gitlab_ci_variable, action instance_list
• Individual tool: gitlab_instance_variable_list
• Tier: Free
• Classic or OAuth token: read_api (or api)
• Fine-grained token: Variable: Read at instance (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
order_by	string	no	Column by which to order keyset-paginated results
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
page_token	string	no	Next page of a keyset listing: the next_page_token of the previous response of this action, passed back unchanged. It carries the position and every filter of the listing as GitLab read them, and those are what the next page is asked with, whatever filters are sent beside it. Leave it empty for the first page.
pagination	string	no	Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost, and a keyset page names the next one in next_page_token rather than next_page.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
sort	string (asc, desc)	no	Sort direction for keyset-paginated results (asc, desc)

ci_variable.instance_update

Update an instance-level CI/CD variable by key, with type and protected/masked/raw flags (admin-only). Returns: the updated variable’s key, value (raw even when masked, because masking redacts CI job logs, not this API), type, protected/masked/raw flags, and description. See also: ci_variable.instance_get, ci_variable.instance_list, ci_variable.instance_delete.

• Meta-tool: gitlab_ci_variable, action instance_update
• Individual tool: gitlab_instance_variable_update
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Variable: Update at instance (permissions page)
• Behavior: writes, idempotent

Parameter	Type	Mandatory	Description
key	string	yes	Variable key name
description	string	no	Updated variable description. Pass an empty string to remove it. Omit the field to leave it untouched
masked	boolean	no	Mask variable value in job logs
protected	boolean	no	Only expose in protected branches/tags
raw	boolean	no	Treat variable value as raw string
value	string	no	Updated variable value. Pass an empty string to empty it. Omit the field to leave it untouched
variable_type	string (env_var, file)	no	Variable type: env_var or file

ci_variable.list

List a project’s CI/CD variables with order_by, sort, and offset or keyset pagination. Returns: each variable’s key, type, protected/masked/hidden/raw flags, environment scope, description, and pagination metadata. See also: ci_variable.get, ci_variable.create, ci_variable.update.

• Meta-tool: gitlab_ci_variable, action list
• Individual tool: gitlab_ci_variable_list
• Tier: Free
• Classic or OAuth token: read_api (or api)
• Fine-grained token: Variable: Read at project (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
order_by	string	no	Column by which to order keyset-paginated results
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
page_token	string	no	Next page of a keyset listing: the next_page_token of the previous response of this action, passed back unchanged. It carries the position and every filter of the listing as GitLab read them, and those are what the next page is asked with, whatever filters are sent beside it. Leave it empty for the first page.
pagination	string	no	Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost, and a keyset page names the next one in next_page_token rather than next_page.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
sort	string (asc, desc)	no	Sort direction for keyset-paginated results (asc, desc)

ci_variable.update

Update a CI/CD variable, selecting an environment-scoped instance via the filter. Returns: the updated variable’s key, value (redacted when masked or hidden), type, protected/masked/hidden/raw flags, environment scope, and description. See also: ci_variable.get, ci_variable.list, ci_variable.delete.

• Meta-tool: gitlab_ci_variable, action update
• Individual tool: gitlab_ci_variable_update
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Variable: Update at project (permissions page)
• Behavior: writes, idempotent

Parameter	Type	Mandatory	Description
key	string	yes	Variable key name
project_id	string/integer	yes	Project ID or URL-encoded path
description	string	no	Updated variable description. Pass an empty string to remove it. Omit the field to leave it untouched
environment_scope	string	no	Filter by environment scope (shorthand for filter.environment_scope)
filter	object	no	Filter selecting the variable by environment scope. Mirrors the GitLab variable filter object
masked	boolean	no	Mask variable value in job logs
protected	boolean	no	Only expose in protected branches/tags
raw	boolean	no	Treat variable value as raw string
value	string	no	Updated variable value. Pass an empty string to empty it. Omit the field to leave it untouched
variable_type	string (env_var, file)	no	Variable type: env_var or file