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.

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. 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
• 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
• 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
• 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
• 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
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
value	string	no	Variable value
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
• 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
• 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
• 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	Keyset pagination cursor: record id at which to fetch the next page, taken from the previous keyset response. Only used when pagination=‘keyset’.
pagination	string	no	Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost.
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
• 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
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
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
• Behavior: writes, not idempotent

Parameter	Type	Mandatory	Description
key	string	yes	Variable key name
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
value	string	no	Variable value
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
• 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
• 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
• 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	Keyset pagination cursor: record id at which to fetch the next page, taken from the previous keyset response. Only used when pagination=‘keyset’.
pagination	string	no	Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost.
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
• Behavior: writes, idempotent

Parameter	Type	Mandatory	Description
key	string	yes	Variable key name
description	string	no	Updated 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
value	string	no	Updated variable value
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
• 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	Keyset pagination cursor: record id at which to fetch the next page, taken from the previous keyset response. Only used when pagination=‘keyset’.
pagination	string	no	Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost.
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
• 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
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
variable_type	string (env_var, file)	no	Variable type: env_var or file