Skip to content

CI/CD variables

Configuring CI/CD variables

CI/CD variables exist at three scopes: instance (gitlab_settings_instance.ci_variables, documented in Instance Administration), group, and project. Group and project variables are unique by key plus environment_scope — each declared (key, scope) pair is reconciled independently and never cross-matched with another scope.

Variable values are write-only secrets

value is write-only and secret: never compared, displayed, or diffed. It is carried on every write (GitLab requires it on update), and force_secret_update: true forces a rotation write when nothing else drifted — declare the new value with the flag, apply, then remove the flag.

Example variables definition

gitlab_settings_groups:
  - path: platform
    variables:
      - key: REGISTRY_TOKEN
        value: "{{ vault_registry_token }}"
        protected: true
        masked: true

gitlab_settings_projects:
  - path: platform/service
    variables:
      - key: DEPLOY_TOKEN
        value: "{{ vault_deploy_token_default }}"
      - key: DEPLOY_TOKEN
        value: "{{ vault_deploy_token_production }}"
        environment_scope: production
        protected: true
      - key: OBSOLETE_VAR
        state: absent

CI/CD Variables Spec

GitLab API reference

GitLab's API documentation defines the fields:

  1. Project variables API
  2. Group variables API

key string Required

Variable name. Together with environment_scope it forms the identity.

 Example: 
variables:
  - key: DEPLOY_TOKEN
...

environment_scope string 

Scope the variable applies to. Part of the identity: the same key may exist at several scopes.

Default: *

 Example: 
variables:
  - key: DEPLOY_TOKEN
    environment_scope: production
...

value string Required when state is present

Required when the variable's state is present (the default). Omit it when state: absent; deletion uses key and environment_scope. The value is secret, write-only, and carried on every write.

 Example: 
variables:
  - key: DEPLOY_TOKEN
    value: "{{ vault_deploy_token }}"
...

force_secret_update boolean 

Rewrite the value on an existing variable even without other drift. Use for rotation, then remove.

Default: false

 Example: 
variables:
  - key: DEPLOY_TOKEN
    value: "{{ new_value }}"
    force_secret_update: true
...

protected boolean 

Limit the variable to protected branches and tags. Reconciles with drift detection.

 Example: 
variables:
  - key: DEPLOY_TOKEN
    protected: true
...

masked boolean 

Mask the variable value in job logs. Reconciles with drift detection.

 Example: 
variables:
  - key: DEPLOY_TOKEN
    masked: true
...

raw boolean 

Disable variable expansion when true. Reconciles with drift detection.

 Example: 
variables:
  - key: DEPLOY_TOKEN
    raw: true
...

variable_type string 

Can be one of: env_var, file. Reconciles with drift detection.

 Example: 
variables:
  - key: DEPLOY_TOKEN
    variable_type: env_var
...

description string 

Human-readable variable description. Reconciles with drift detection.

 Example: 
variables:
  - key: DEPLOY_TOKEN
    description: Deployment credential
...

masked_and_hidden boolean 

Hide the variable after creation. GitLab reports this as hidden and does not allow it to change, so it is accepted at creation only; changing it requires recreating the variable.

 Example: 
variables:
  - key: DEPLOY_TOKEN
    masked_and_hidden: true
...

state string 

Lifecycle per (key, scope) pair.

Can be one of: present, absent

Default: present

 Example: 
variables:
  - key: OBSOLETE_VAR
    environment_scope: production
    state: absent
...