Variables & Secrets

Jobs receive variables from multiple sources, layered by precedence (lowest to highest):

Priority	Source	How to set
1 (lowest)	CI-derived	Automatic (git SHA, branch, etc.)
2	Global YAML	`variables:` at top of `.gitlab-ci.yml`
3	Group variables	Fetched from GitLab API
4	Project variables	Fetched from GitLab API
5	`--env` flags	`glci run --env KEY=VALUE`
6	`--env-file`	`glci run --env-file .env.local`
7	`.glci.env`	Auto-loaded from project root (add to `.gitignore`)
8	Dotenv artifacts	`artifacts: reports: dotenv:` from dependency jobs
9 (highest)	Job YAML	`variables:` inside a job definition

Remote secrets#

Project and group CI/CD variables are fetched automatically when a GitLab token is available. Results are cached in daemon memory for 6 hours (never written to disk). The cache is lost on daemon restart.

glci run --secrets all      # project + group variables (default)
glci run --secrets project  # project variables only
glci run --secrets none     # skip remote fetching entirely
glci run --refresh-secrets  # force a fresh fetch, bypassing the cache

Configure the cache TTL in .glciconfig.toml:

[gitlab]
secrets_ttl = "6h"   # default; set to "0" to disable caching

Local overrides with `.glci.env`#

Auto-loaded KEY=VALUE file from project root for local secrets. Add it to .gitignore. Masked and file-type variable attributes from the GitLab API are preserved and passed to the runner.

Token forwarding#

By default, the host’s real GitLab token is forwarded into jobs as CI_JOB_TOKEN. Disable with --no-token, or restrict which jobs receive it in .glciconfig.toml:

[token]
forward_host_token = true
stages = ["deploy"]              # only deploy stage gets real token
jobs = ["release"]               # specific job names
job_patterns = [".*-publish$"]   # regex patterns

Jobs not matching the filter receive a synthetic mock-server token instead.

GitLab API token#

Required for include: project:, include: component:, fetching remote CI/CD variables, and auto-cloning trigger: project: targets.

Token resolution order (first match wins; --token flag always overrides):

GITLAB_TOKEN or GITLAB_PRIVATE_TOKEN environment variable
[gitlab] token in .glciconfig.toml / ~/.glci/config.toml
glab auth credential-helper – supports keyring, OAuth2 refresh, and PAT/CI tokens
Direct read of ~/.config/glab-cli/config.yml – legacy fallback

The simplest setup is glab auth login – the token is picked up automatically. The project path is auto-detected from your git remote; override with --project.

Fallback project path#

When no git remote is configured (common for local-only test repos), CI_PROJECT_PATH defaults to local/<dirname> so variables like $CI_PROJECT_PATH are always available in job scripts.

Unsupported variables#

About 20 CI/CD variables cannot be set locally because they require a real GitLab server: CI_DEPLOY_*, CI_UPSTREAM_*, CI_EXTERNAL_PULL_REQUEST_*, KUBECONFIG, CHAT_*. GITLAB_USER_* variables are approximated from git config.

`GLCI_PREFER_API`#

Set GLCI_PREFER_API=1 to use the GitLab Lint API as the primary parser instead of the offline parser. Useful for edge cases where the offline parser differs from GitLab’s server-side behavior.

Context-derived variables#

glci sets CI variables based on the --context flag. See Context Simulation for the full variable table per context type.

Edit on GitLab Report issue