CI Cache
glci implements cache: via an S3-compatible endpoint on the embedded mock server, backed by a persistent Docker volume. Cache entries survive across pipeline runs without requiring an external S3 bucket or GCS backend.
All standard cache: keywords (key, key: files:, key: prefix:, fallback_keys, paths, policy, when, untracked, multiple caches per job) work the same as production GitLab CI. See the GitLab CI caching documentation for usage details.
How it works#
Cache entries live in the glci-cache Docker volume. The mock server exposes S3-compatible endpoints that gitlab-runner uses via its built-in S3 cache adapter. Compression uses tarzstd at the fastest level.
When [cache] persistent = true (the default), the daemon syncs cache entries to the persistent volume at pipeline completion and preloads them into new mock server containers on the next run.
Configuration#
Configure cache behavior in .glciconfig.toml:
[cache]
persistent = true # default; persist cache across pipeline runs
max_size = "500MB" # reject uploads when total cache exceeds this
ttl = "24h" # expire entries older than this duration
| Setting | Default | Description |
|---|---|---|
persistent | true | Sync cache entries to persistent Docker volume |
max_size | 500MB | Maximum total cache size; uploads rejected (HTTP 507) when exceeded |
ttl | 24h | Time-to-live for individual entries; expired entries are pruned on upload and rejected on download |
A single cache entry is capped at 5 GB.
Clearing the cache#
# Remove all CI cache entries
glci system cache clean
This removes the glci-cache Docker volume. The volume is recreated automatically on the next pipeline run. If the daemon is running, it is stopped and restarted automatically.
You can also clear cache as part of a broader cleanup:
# Remove unused containers, networks, volumes, and CI cache
glci system prune
# Remove everything including registry data and history
glci system prune --all
Differences from production GitLab CI#
| Aspect | glci | Production GitLab |
|---|---|---|
| Storage backend | Local Docker volume via mock S3 | S3, GCS, or Azure (configurable per-runner) |
| Network latency | Zero (local Docker) | Depends on bucket region |
| Cache scope | All local pipelines share the cache | Scoped by project and (optionally) protected branches |
unprotect | Parsed but not enforced (no protected branch concept locally) | Controls cache sharing between protected and unprotected branches |
| Size limit | Configurable via [cache] max_size (default 500 MB) | Depends on storage backend |
| Max entry size | 5 GB per entry | Depends on storage backend |
File-based key computation uses the same MD5 algorithm as GitLab Rails, so cache keys are identical between local and production runs.
Troubleshooting#
Cache uploads rejected (507)#
The total cache size has exceeded max_size. Clear old entries:
glci system cache clean
Or increase the limit in .glciconfig.toml:
[cache]
max_size = "1GB"
Cache not persisting between runs#
Check that persistence is enabled (it is by default):
[cache]
persistent = true
If persistent = false, cache only lives for the duration of a single mock server container.
Stale cache causing build failures#
Force a clean run:
glci system cache clean
glci run