# set-gitlab-vars

Universal script for setting GitLab CI/CD variables via API.

## Features
- 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](https://github.com/mikefarah/yq/#install))

## Usage

### 1. Bulk from YAML file
```sh
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
```yaml
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
```sh
./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
```sh
./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`)

1. Convert your YAML to JSON (if needed):
```sh
yq -o=json path/to/file.yml > file.json
```
2. Validate with `ajv`:
```sh
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

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

2. Validate your YAML file:
   ```sh
   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
```yaml
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](LICENSE).