Environment Variables

glci reads environment variables to control its own behavior and sets CI/CD variables inside job containers to emulate GitLab CI. This page covers both categories.

glci control variables#

These variables configure glci itself. Set them in your shell or .glci.env before running glci.

Paths & data directory#

Variable	Default	Description
`GLCI_HOME`	`~/.glci`	Override the data directory where glci stores daemon state, pipeline history, registry data, and logs. Useful for test isolation or running multiple daemon instances.
`GLCI_NO_DEFAULT_CONFIG`	(unset)	Set to `1` to prevent glci from auto-creating a `.glciconfig.toml` when none exists. By default, glci creates one with `[skip] stages = [".pre"]`.

# Use a custom data directory
export GLCI_HOME=/tmp/glci-test
glci run

# Disable auto-creation of .glciconfig.toml
GLCI_NO_DEFAULT_CONFIG=1 glci run

Daemon#

Variable	Default	Description
`GLCI_DAEMON_SOCK`	`~/.glci/daemon.sock`	Override the Unix socket path for daemon communication. Useful when running parallel daemon instances (e.g. in CI).

export GLCI_DAEMON_SOCK=/tmp/my-glci.sock
glci run

Docker#

Variable	Default	Description
`DOCKER_HOST`	(auto-detected)	Docker daemon endpoint. glci resolves this at startup via: (1) `[docker] host` in config, (2) active Docker context, (3) inherited `DOCKER_HOST`, (4) Docker CLI defaults.
`DOCKER_CONFIG`	`~/.docker`	Directory containing Docker `config.json`. Used for Docker Hub credentials that are propagated into DinD containers.

# Point glci at a remote Docker daemon
export DOCKER_HOST=ssh://remote-host
glci run

# Use a custom Docker config directory
export DOCKER_CONFIG=/path/to/docker-config
glci run

GitLab API#

Variable	Default	Description
`GITLAB_URL`	(auto-detected from git remote)	GitLab instance URL. Overrides auto-detection from git remote and config file settings. Falls back to `https://gitlab.com`.
`GITLAB_TOKEN`	(unset)	GitLab personal access token or CI job token. Used for cross-project includes, fetching remote CI/CD variables, and auto-cloning trigger targets.
`GITLAB_PRIVATE_TOKEN`	(unset)	Alias for `GITLAB_TOKEN`. If both are set, `GITLAB_TOKEN` takes precedence.

export GITLAB_URL=https://gitlab.example.com
export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
glci run

Parsing behavior#

Variable	Default	Description
`GLCI_PREFER_API`	(unset)	Set to `1` to use the GitLab Lint API as the primary CI config parser instead of the offline parser. The offline parser is the default (with API as fallback).

GLCI_PREFER_API=1 glci run

Cache (internal, mock server)#

These variables are set internally by the daemon when launching the mock server container. They are documented here for completeness but are not typically set by users.

Variable	Default	Description
`GLCI_MOCK_PORT`	`39741`	Port the mock server listens on inside its container. Set by the daemon from the resolved `mock_server_port` config value. Configurable via `[network] mock_server_port` in `config.toml`.
`GLCI_CACHE_DIR`	(unset)	Disk-backed cache directory for the mock server. Set by the daemon to `/cache-store` inside the mock container. When unset, cache stays in memory.
`GLCI_CACHE_MAX_SIZE`	`500MB`	Maximum total size for CI cache entries. Uploads are rejected when this limit is exceeded. Accepts suffixes: `KB`, `MB`, `GB`.
`GLCI_CACHE_TTL`	`24h`	Time-to-live for cached entries. Entries older than this are expired. Uses Go duration format (e.g. `1h30m`, `24h`).

Editor#

Variable	Default	Description
`EDITOR`	(unset)	Used by `glci config edit` to open the project config file. Falls back to `VISUAL` if unset.
`VISUAL`	(unset)	Fallback editor when `EDITOR` is not set.

export EDITOR=vim
glci config edit

Simulation#

Variable	Description
`GLCI_SIMULATE`	Set to `true` inside job containers when running in `--simulate` mode. Not typically set by users; scripts can check this to detect simulation.

CI/CD variables set in jobs#

glci populates standard GitLab CI/CD predefined variables inside job containers. Commit, project, server, pipeline, job, user, and runner variables are all derived from local git state and mock server configuration, matching what GitLab CI would set.

The following variables behave differently in glci compared to GitLab CI:

Variables with fixed/local values#

Variable	glci value	Why it differs
`CI_COMMIT_BEFORE_SHA`	`0000000000...` (null SHA)	No previous pipeline to compare against locally
`CI_COMMIT_REF_PROTECTED`	`false`	Protected branch status is not available locally
`CI_PROJECT_ID`	`0`	No real project ID locally
`CI_PROJECT_NAMESPACE_ID`	`0`	No real namespace ID locally
`CI_PROJECT_VISIBILITY`	`private`	Not detectable locally
`CI_PIPELINE_IID`	Same as `CI_PIPELINE_ID`	No project-scoped counter separation locally
`GITLAB_USER_LOGIN`	Same as `GITLAB_USER_NAME`	No GitLab account mapping; uses `git config user.name`
`GITLAB_USER_ID`	`0`	No real user ID locally
`CI_RUNNER_ID`	`1` (default runner)	Per-runner ID; named runners (`[runners.<name>]`) get unique IDs
`CI_RUNNER_DESCRIPTION`	`glci-local-runner` (default runner)	Per-runner description; named runners use their container name
`CI_JOB_TOKEN`	Synthetic mock token	Unless real token is forwarded via `[token]` config

Registry variables#

Set when the embedded container registry is active (default).

Variable	Source
`CI_REGISTRY`	Embedded registry address (e.g. `host.docker.internal:12345`)
`CI_REGISTRY_USER`	`gitlab-ci-token`
`CI_REGISTRY_PASSWORD`	Set per-job; equals `CI_JOB_TOKEN`
`CI_REGISTRY_IMAGE`	Registry address + project path
`DOCKER_AUTH_CONFIG`	Docker auth JSON merged with host `~/.docker/config.json`

Environment and release variables#

CI_ENVIRONMENT_* variables are set when a job has an environment: keyword. CI_RELEASE_DESCRIPTION is set when a job has a release: keyword (truncated to 1024 chars).

Merge request variables#

Set when using --context merge_request.

Variable	glci value
`CI_PIPELINE_SOURCE`	`merge_request_event`
`CI_MERGE_REQUEST_SOURCE_BRANCH_NAME`	Current git branch (or `--mr-source`)
`CI_MERGE_REQUEST_TARGET_BRANCH_NAME`	Default branch (or `--mr-target`)
`CI_MERGE_REQUEST_IID`	`1`
`CI_MERGE_REQUEST_TITLE`	`local`

Variable precedence#

See Variables & Secrets for the full precedence table and details on remote secrets, .glci.env, and token resolution.

Edit on GitLab Report issue