135 lines
4.4 KiB
Markdown
135 lines
4.4 KiB
Markdown
# 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).
|
|
|