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#

# 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#

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

Container engine (Docker / Podman)#

The config keys that back these variables — [docker] engine/host/container_socket and the per-runner engine, docker_host, docker_context, container_socket, tls_cert_path, tls_verify — are honored only in ~/.glci/config.toml. A project .glciconfig.toml that sets them has them dropped with a warning. See Config files > Container-endpoint keys.

Whenever a named runner targets its own endpoint — via either docker_host or docker_context — glci strips DOCKER_HOST, DOCKER_CONTEXT, CONTAINER_HOST, CONTAINER_CONNECTION, CONTAINER_SSHKEY, DOCKER_CERT_PATH, and DOCKER_TLS_VERIFY from that command’s environment before applying the runner’s own settings. The --context/--connection flags do outrank the variables, so for that path stripping is defence in depth; it is load-bearing for the raw-endpoint path, because Podman ranks CONTAINER_CONNECTION above CONTAINER_HOST and would otherwise send a runner that sets docker_host to whatever connection the ambient variable names.

Endpoint resolution order#

The daemon resolves one endpoint at startup, mirroring each engine’s own precedence:

Only [docker] host outranks the environment. Two endpoint values are refused rather than passed to the engine:

• A value whose scheme is not unix://, tcp://, ssh://, npipe://, or fd:// is ignored with a log line (a bogus unix:// path would otherwise become the socket bind-mount source inside runner containers).
• Whitespace-only values, from either the environment or a heredoc-written config, are treated as unset.

When the endpoint does not come from the environment (config, context, or connection), glci also drops inherited DOCKER_CERT_PATH/DOCKER_TLS_VERIFY: those name trust anchors for one specific daemon, and keeping them against a different endpoint is a false assurance of TLS.

Because the TLS variables are Docker-only, a runner with engine = "podman" and a tcp:// docker_host gets no TLS even with tls_cert_path/tls_verify set (glci config --network warns about this). For a remote Podman endpoint, use an ssh:// endpoint — Podman’s only authenticated and encrypted remote transport. A podman system connection referenced via docker_context is only as secure as its own URI: a connection pointing at tcp:// is still unencrypted and unauthenticated.

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

# Point glci at a remote Podman endpoint
export CONTAINER_HOST=ssh://podman-host
glci run

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

An exported endpoint variable takes precedence over the active Docker context (and over the default podman system connection), matching how the docker and podman CLIs themselves behave. So a remote daemon can be selected per shell, with no config file changes:

DOCKER_HOST=tcp://build-box:2375 glci run

Security: glci sends more to the resolved endpoint than docker alone does — the repository tree, your ~/.docker/config.json registry credentials, and the forwarded GitLab token all land on that daemon. A plain tcp:// endpoint carries them unencrypted and unauthenticated, so glci prints a warning when it resolves one without TLS. Prefer ssh://, or configure Docker TLS.

Endpoint changes and the shared daemon#

The glci daemon is process-global and resolves its endpoint once at startup, inheriting the environment of the CLI invocation that spawned it. A later command that selects a different endpoint does not restart it — glci reports the mismatch once and leaves the daemon alone:

glci: warning: daemon is using unix:///var/run/docker.sock but $DOCKER_HOST selects tcp://build-box:2375
glci:          run `glci daemon stop` to pick it up (the daemon re-starts on the next command)

Restarting is deliberately not automatic. Endpoint selection is per-shell while the daemon is global, so auto-restarting would let two shells with different DOCKER_HOST values evict each other’s daemon on every command — and a restart races any pipeline that starts while it is being decided. glci daemon stop is the explicit switch; the daemon re-starts with the new endpoint on the next command. If pipelines are still running, the warning says how many, because stopping the daemon cancels them.

Four mismatches are reported:

• A different endpoint is selected than the daemon resolved.
• An explicit selection was removed — you ran DOCKER_HOST=… glci run earlier and this shell has none. Without this, a one-shot variable would keep serving every later clean shell for the daemon’s whole lifetime.
• The selection is for the other engine — an unreachable DOCKER_HOST makes a fresh daemon fall back to Podman, which would silently drop the endpoint you asked for.
• A different context/connection is selected — DOCKER_CONTEXT/CONTAINER_CONNECTION differs from the name the daemon resolved with. The name is compared, not the endpoint it maps to, so this costs no subprocess.

One case is not detected: running docker context use other, which changes the current context on disk without changing any variable. Catching that would mean asking the docker CLI for the context’s endpoint on every glci command. glci daemon status and glci doctor both report the endpoint in use (and the context it came from), and doctor says explicitly when a value was not compared.

GitLab API#

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

Parsing behavior#

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.

Editor#

export EDITOR=vim
glci config edit

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#

Registry variables#

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

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 precedence#

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