Content-addressed CI
build cache for Kubernetes

Deduplicated, secure, backend-agnostic caching for Rust, npm, and Docker workloads. Runs inside your cluster with zero external dependencies.

$curl -fsSL https://github.com/rileyseaburg/cluster-ci-cache/releases/latest/download/install.sh | bashCOPY

Installs ci-cache CLI, server, and agent. Click to copy.

Download v0.1.0 Documentation

Features

Not a key-value store. A content-addressed artifact fabric with manifest-level deduplication, digest verification, and path-traversal hardening.

storage

Content-addressed blobs

Every blob stored by its SHA-256 digest. Identical content across cache keys, namespaces, and types deduplicates automatically — store once, reference everywhere.

security

Archive hardening

Custom archive format with path traversal protection, absolute path rejection, symlink skipping, decompression bomb limits, and digest verification on upload and restore.

backends

Backend-agnostic

Filesystem and PVC backend for zero-dependency local dev. S3 and MinIO backend for production shared storage. Same HTTP API regardless of backend.

k8s

Kubernetes-native

Deployment with replicas, DaemonSet agent, ServiceAccount, RBAC, ConfigMap, NetworkPolicy, PVC. Health and readiness probes. Helm chart included.

metrics

Observable

Prometheus metrics for hits, misses, bytes transferred, dedup ratio, and latency histograms. Structured JSON logs. Standard healthz and readyz endpoints.

concurrency

Concurrency-safe

Atomic manifest publishing via temp-file-and-rename. Save sessions prevent partial manifests. Idempotent blob storage. No distributed locks required for correctness.

Architecture

A central server manages manifests and content-addressed blobs. A node-local agent provides health and locality for future caching layers. The CLI runs inside CI jobs.

topology

  CI Job Pod                        ci-cache-server                   Backend
  +-----------+                     +------------------+              +----------+
  | ci-cache  |--- 1. restore ----->| manifest lookup  |--- get ----->| FS / PVC |
  | (CLI)     |<--- manifest -------| dedup check      |<--- blob ----| S3/MinIO |
  |           |--- 2. save -------->| session create   |              +----------+
  |           |--- upload blob ---->| verify + store   |
  |           |--- finish --------->| atomic publish   |
  +-----------+                     +------------------+
                                          |
                                   +------------------+
                                   | ci-cache-agent   |
                                   | (DaemonSet)      |
                                   +------------------+

Quick Start

Three steps: install, deploy, use. Works with any CI runner inside Kubernetes.

terminal

// Install the CLI
curl -fsSL https://github.com/rileyseaburg/cluster-ci-cache/releases/latest/download/install.sh | bash

terminal

// Deploy to Kubernetes
kubectl apply -k deploy/k8s/

shell

// Use in CI
export CI_CACHE_SERVER=http://ci-cache-server.ci-cache.svc.cluster.local:8080
LOCK_HASH=$(sha256sum Cargo.lock | cut -d' ' -f1)

ci-cache restore \
  --cache-type cargo \
  --key cargo-linux-$LOCK_HASH \
  --paths ~/.cargo/registry,~/.cargo/git,target

cargo build --release

// Save after build
ci-cache save \
  --cache-type cargo \
  --key cargo-linux-$LOCK_HASH \
  --paths ~/.cargo/registry,~/.cargo/git,target

Supports cargo, npm, pnpm, yarn, docker, and generic cache types. See documentation for all options.

Project Status

Deployed and verified on a 7-node Kubernetes cluster. E2E cache miss, save, hit, and restore cycle confirmed.

Rust crates

3,424

Lines of code

Tests passing

101 MB

Container image

2 + 6

Server + agent pods

v0.1.0

First release

metrics

ci_cache_restore_requests_total 2
ci_cache_save_requests_total 1
ci_cache_hits_total 1
ci_cache_misses_total 1
ci_cache_bytes_uploaded_total 249
ci_cache_bytes_downloaded_total 498
ci_cache_blob_dedup_hits_total 1
ci_cache_backend_errors_total 0