Architecture
Understand glci’s internal architecture — the mock GitLab API server, persistent runner, embedded registry, and Docker-in-Docker support.
Overview#
glci runs your .gitlab-ci.yml pipeline locally by placing a mock GitLab API server between the official gitlab-runner binary and your CI configuration. The runner believes it is talking to a real GitLab instance. Jobs execute in real containers with the same shell scripts, image pulls, and lifecycle that GitLab CI uses in production. The container engine can be either Docker or Podman, selected via [docker] engine (gitlab-runner keeps executor = "docker" in both cases).
The system has four main layers:
| Layer | Component | What it does |
|---|---|---|
| CLI | glci run, glci show, TUI | Parses CI config, sends requests to daemon, renders output |
| Daemon | Background process (~/.glci/daemon.sock) | Manages pipeline lifecycle, crash recovery, event streaming |
| Mock server | glci-mock container | Implements GitLab API, git HTTP, artifacts, cache, OCI registry |
| Runner | glci-runner container | Official gitlab-runner executing jobs in Docker containers |
In this section#
- How It Works — pipeline execution lifecycle, mock server API, CI config parsing, job dispatch
- Embedded Registry — OCI registry, pull-through cache, push-through mirroring
- Docker-in-Docker — DinD support, buildx, QEMU, cross-platform builds
- How It Works — Mock server, runner, and pipeline infrastructure
- Embedded Registry — OCI registry built into the mock server
- Docker-in-Docker — DinD support, buildx, QEMU, and cross-platform builds