Set variables in bulk from a YAML file or individually via CLI arguments
Supports all GitLab variable options: environment scope, variable type (env_var/file), protected, raw, masked, masked_and_hidden, and description
Handles both creation and update of variables (idempotent)
Supports multiline and special characters for file and env_var types
YAML input supports full variable configuration, including descriptions
CLI input supports quick single variable setting

Requirements

Bash (Linux/macOS)
curl
yq (for YAML input, see yq installation)

Usage

1. Bulk from YAML file

export GITLAB_URL="https://gitlab.example.com"
export PROJECT=1 # or export PROJECT=owner_or_group/repo
export GITLAB_TOKEN=... # token with api scope
./set-gitlab-vars path/to/file.yml

YAML file structure

MY_SECRET:
  value: "supervalue"           # required
  environment_scope: "Dev"      # optional
  variable_type: "file"         # optional (default: env_var)
  protected: true                # optional (default: false)
  raw: false                     # optional (default: true)
  masked: false                  # optional (default: false)
  masked_and_hidden: false       # optional (default: false)
  description: "Secret for Dev"  # optional (default: null)

2. Single variable via arguments

./set-gitlab-vars VAR_NAME VAR_VALUE [ENV_SCOPE] [VAR_TYPE] [PROTECTED] [RAW] [MASKED] [MASKED_AND_HIDDEN]
# Example:
./set-gitlab-vars MY_SECRET "supervalue" "Production" "file" true true false false

Only VAR_NAME and VAR_VALUE are required. Other options are optional and default as in YAML.
description is only supported via YAML.

3. Help

./set-gitlab-vars --help

Required Environment Variables

GITLAB_URL — GitLab address (e.g. https://gitlab.example.com)
PROJECT — project ID or path (e.g. 1 or owner_or_group/repo)
GITLAB_TOKEN — token with api scope

Notes

All boolean options (protected, raw, masked, masked_and_hidden) default to false except raw (default: true).
For file variables, multiline and special characters are supported.
For env_var variables, multiline values are supported via form-data.
All options are supported both in YAML and via CLI (except description, which is YAML only).

Error Handling

The script will print errors and exit if required environment variables are missing or if the GitLab API returns an error.
If a variable already exists, it will be updated instead of created.

JSON Schema for YAML Validation

A JSON schema file gitlab-vars-schema.json is included in this repository. You can use it to validate your YAML variable files for correctness and completeness before applying them with set-gitlab-vars.

Usage Example (with `yamllint` and `ajv`)

Convert your YAML to JSON (if needed):

yq -o=json path/to/file.yml > file.json

Validate with ajv:

ajv validate -s gitlab-vars-schema.json -d file.json

The schema ensures all required fields and types are correct for each variable.
This helps catch errors early and maintain consistency in your CI/CD variable definitions.

For more details on the schema, see the gitlab-vars-schema.json file.

Yamale Schema Validation

A Yamale schema (gitlab-vars.yamale) is provided for validating your GitLab CI/CD variables YAML files.

Example Usage

Install Yamale (if not already installed):
```
pip install yamale
```

Validate your YAML file:

yamale -s gitlab-vars.yamale path/to/your-vars.yml

Each top-level key in your YAML file should be a variable name.
The value for each variable is a mapping with the following fields:
- value (string, required)
- environment_scope (string, optional)
- variable_type (string, optional)
- protected (boolean, optional)
- raw (boolean, optional)
- masked (boolean, optional)
- masked_and_hidden (boolean, optional)
- description (string or null, optional)

Example YAML file

MY_SECRET:
  value: "supervalue"
  environment_scope: "Dev"
  variable_type: "file"
  protected: true
  raw: false
  masked: false
  masked_and_hidden: false
  description: "Secret for Dev"

For more details, see the gitlab-vars.yamale file.

License

See LICENSE.

README.md

set-gitlab-vars

Features