Prerequisites

Required#

No gitlab-runner binary is needed on the host – glci runs the official gitlab/gitlab-runner Docker image automatically.

Optional#

GitLab token#

A token is needed for include: project:, include: component:, CI/CD variables, and cross-project triggers. Token resolution order:

1. --token flag
2. GITLAB_TOKEN environment variable
3. glab auth credential-helper (if glab is installed and authenticated via glab auth login)
4. [gitlab] token in ~/.glci/config.toml or .glciconfig.toml

Verify your token source with glci config --gitlab.

Platform support#

On macOS, Colima (colima start) is recommended. It exposes the Docker socket at the default location with no extra configuration.

On Linux, ensure your user is in the docker group (or use rootless Docker).

Port requirements#

glci publishes the mock server on port 39741 (default) of the Docker host. This port must be available (not used by another process) on every Docker host where glci runs. CI job containers reach the mock server through this port via Docker’s host-gateway mechanism.

The port is configurable via mock_server_port in ~/.glci/config.toml:

[network]
mock_server_port = 39741   # default

Note: Changing this port requires a full daemon restart (glci daemon stop && glci daemon start). A running daemon will continue using the port it started with.

If the port is already in use, glci will fail to start the mock server. See Troubleshooting > Port conflicts for diagnosis steps.

Remote Docker daemons#

Remote Docker daemons (DOCKER_HOST=tcp://..., Docker contexts, cloud-hosted Docker) are supported. glci detects the endpoint in this order:

1. [docker] host in ~/.glci/config.toml
2. Active Docker context (docker context inspect)
3. DOCKER_HOST environment variable
4. Default Docker socket

For remote daemons, glci uses a docker exec transport instead of bind mounts, so no shared filesystem is required between the glci host and the Docker daemon.

[docker]
host = "tcp://remote-host:2375"   # or "ssh://remote-host"

Note: Use glci system prune instead of docker system prune on shared remote hosts – it only cleans glci-specific resources.