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 Docker containers with the same shell scripts, image pulls, and lifecycle that GitLab CI uses in production.
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