Variables de CI/CD

Variables de CI/CD en los tres ámbitos en los que GitLab las guarda: un proyecto, un grupo y la instancia, cada uno con las mismas cinco operaciones. Una variable puede ser protegida, enmascarada o enmascarada y oculta, y las de proyecto y de grupo pueden limitarse a un entorno, así que una clave puede tener un valor distinto en cada entorno. Las variables de instancia necesitan un administrador, y borrar una variable no se puede deshacer.

Preguntas de ejemplo

• “Lista las variables de CI/CD del proyecto 42”
• “Añade una variable enmascarada DEPLOY_TOKEN limitada a production”
• “¿Qué variables de grupo define el grupo platform?”

Cómo llamarlo

• Dinámica, la superficie predeterminada: llama a gitlab_execute_action con action igual al ID de la acción, como ci_variable.create, y sus parámetros en params. gitlab_find_action encuentra un ID a partir de una descripción de la tarea.
• Meta (GITLAB_MCP_TOOL_SURFACE=meta): llama a gitlab_ci_variable con action igual al nombre de la acción, como create, y sus parámetros en params.
• Individual (GITLAB_MCP_TOOL_SURFACE=individual): llama a la herramienta propia de la acción, como gitlab_ci_variable_create, pasándole directamente sus parámetros.

Disponibilidad

Todos los niveles sirven el grupo completo, tanto en instancias autogestionadas como en GitLab.com.

Acciones de solo lectura: 6 de 15, las que conserva un despliegue en modo de solo lectura. A un token con read_api y sin api se le sirven 6 de las 15.

Acciones

La descripción de cada acción, y la de cada uno de sus parámetros, es el texto que sirve el servidor para ella en la superficie predeterminada, citado tal cual; por eso está en inglés. Las líneas de token dicen lo que exige GitLab 19.4.1 a un token para las peticiones que envía cada acción; en una instancia con Admin Mode activado, una acción que solo puede ejecutar un administrador necesita además admin_mode. Una acción destructiva solo se ejecuta una vez confirmada, salvo que GITLAB_MCP_YOLO_MODE (o AUTOPILOT) se salte ese paso: la superficie dinámica necesita confirm: true en gitlab_execute_action, y las otras dos aceptan un parámetro confirm o la pregunta del cliente (Acciones destructivas).

Acción	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-herramienta: gitlab_ci_variable, acción create
• Herramienta individual: gitlab_ci_variable_create
• Nivel: Free
• Token clásico u OAuth: api
• Token de grano fino: Variable: Create en proyecto (página de permisos)
• Comportamiento: escribe, no idempotente

Parámetro	Tipo	Requerido	Descripción
key	string	sí	Variable key name
project_id	string/integer	sí	Project ID or URL-encoded path
value	string	sí	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-herramienta: gitlab_ci_variable, acción delete
• Herramienta individual: gitlab_ci_variable_delete
• Nivel: Free
• Token clásico u OAuth: api
• Token de grano fino: Variable: Delete en proyecto (página de permisos)
• Comportamiento: escribe, destructiva (necesita confirmación), idempotente

Parámetro	Tipo	Requerido	Descripción
key	string	sí	Variable key name
project_id	string/integer	sí	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-herramienta: gitlab_ci_variable, acción get
• Herramienta individual: gitlab_ci_variable_get
• Nivel: Free
• Token clásico u OAuth: read_api (o api)
• Token de grano fino: Variable: Read en proyecto (página de permisos)
• Comportamiento: solo lectura, idempotente

Parámetro	Tipo	Requerido	Descripción
key	string	sí	Variable key name
project_id	string/integer	sí	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-herramienta: gitlab_ci_variable, acción group_create
• Herramienta individual: gitlab_group_variable_create
• Nivel: Free
• Token clásico u OAuth: api
• Token de grano fino: Variable: Create en grupo (página de permisos)
• Comportamiento: escribe, no idempotente

Parámetro	Tipo	Requerido	Descripción
group_id	string/integer	sí	Group ID or URL-encoded path
key	string	sí	Variable key name
value	string	sí	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-herramienta: gitlab_ci_variable, acción group_delete
• Herramienta individual: gitlab_group_variable_delete
• Nivel: Free
• Token clásico u OAuth: api
• Token de grano fino: Variable: Delete en grupo (página de permisos)
• Comportamiento: escribe, destructiva (necesita confirmación), idempotente

Parámetro	Tipo	Requerido	Descripción
group_id	string/integer	sí	Group ID or URL-encoded path
key	string	sí	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-herramienta: gitlab_ci_variable, acción group_get
• Herramienta individual: gitlab_group_variable_get
• Nivel: Free
• Token clásico u OAuth: read_api (o api)
• Token de grano fino: Variable: Read en grupo (página de permisos)
• Comportamiento: solo lectura, idempotente

Parámetro	Tipo	Requerido	Descripción
group_id	string/integer	sí	Group ID or URL-encoded path
key	string	sí	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-herramienta: gitlab_ci_variable, acción group_list
• Herramienta individual: gitlab_group_variable_list
• Nivel: Free
• Token clásico u OAuth: read_api (o api)
• Token de grano fino: Variable: Read en grupo (página de permisos)
• Comportamiento: solo lectura, idempotente

Parámetro	Tipo	Requerido	Descripción
group_id	string/integer	sí	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-herramienta: gitlab_ci_variable, acción group_update
• Herramienta individual: gitlab_group_variable_update
• Nivel: Free
• Token clásico u OAuth: api
• Token de grano fino: Variable: Update en grupo (página de permisos)
• Comportamiento: escribe, idempotente

Parámetro	Tipo	Requerido	Descripción
group_id	string/integer	sí	Group ID or URL-encoded path
key	string	sí	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-herramienta: gitlab_ci_variable, acción instance_create
• Herramienta individual: gitlab_instance_variable_create
• Nivel: Free
• Token clásico u OAuth: api
• Token de grano fino: Variable: Create en instancia (página de permisos)
• Comportamiento: escribe, no idempotente

Parámetro	Tipo	Requerido	Descripción
key	string	sí	Variable key name
value	string	sí	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-herramienta: gitlab_ci_variable, acción instance_delete
• Herramienta individual: gitlab_instance_variable_delete
• Nivel: Free
• Token clásico u OAuth: api
• Token de grano fino: Variable: Delete en instancia (página de permisos)
• Comportamiento: escribe, destructiva (necesita confirmación), idempotente

Parámetro	Tipo	Requerido	Descripción
key	string	sí	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-herramienta: gitlab_ci_variable, acción instance_get
• Herramienta individual: gitlab_instance_variable_get
• Nivel: Free
• Token clásico u OAuth: read_api (o api)
• Token de grano fino: Variable: Read en instancia (página de permisos)
• Comportamiento: solo lectura, idempotente

Parámetro	Tipo	Requerido	Descripción
key	string	sí	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-herramienta: gitlab_ci_variable, acción instance_list
• Herramienta individual: gitlab_instance_variable_list
• Nivel: Free
• Token clásico u OAuth: read_api (o api)
• Token de grano fino: Variable: Read en instancia (página de permisos)
• Comportamiento: solo lectura, idempotente

Parámetro	Tipo	Requerido	Descripción
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-herramienta: gitlab_ci_variable, acción instance_update
• Herramienta individual: gitlab_instance_variable_update
• Nivel: Free
• Token clásico u OAuth: api
• Token de grano fino: Variable: Update en instancia (página de permisos)
• Comportamiento: escribe, idempotente

Parámetro	Tipo	Requerido	Descripción
key	string	sí	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-herramienta: gitlab_ci_variable, acción list
• Herramienta individual: gitlab_ci_variable_list
• Nivel: Free
• Token clásico u OAuth: read_api (o api)
• Token de grano fino: Variable: Read en proyecto (página de permisos)
• Comportamiento: solo lectura, idempotente

Parámetro	Tipo	Requerido	Descripción
project_id	string/integer	sí	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-herramienta: gitlab_ci_variable, acción update
• Herramienta individual: gitlab_ci_variable_update
• Nivel: Free
• Token clásico u OAuth: api
• Token de grano fino: Variable: Update en proyecto (página de permisos)
• Comportamiento: escribe, idempotente

Parámetro	Tipo	Requerido	Descripción
key	string	sí	Variable key name
project_id	string/integer	sí	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