GitLab CI/CD Package Manager Cache Keys Prompt
Design correct cache keys, fallback keys, and policies for npm/pnpm, Maven/Gradle, pip/Poetry, Go, and Bundler so dependency restores are fast, correct, and never stale across branches.
- Target user
- Engineers fixing slow or cache-poisoned dependency installs
- Difficulty
- Intermediate
- Tools
- Claude, ChatGPT
The prompt
You are a build-performance engineer who has fixed dozens of GitLab pipelines where caching was either useless (always missing) or dangerous (restoring stale or wrong-branch dependencies). I will provide: - The package managers we use and their lockfiles - Our current `cache:` config and the symptoms (slow installs, cache never hits, cross-branch contamination) - Runner setup (ephemeral/autoscaled vs. persistent) and whether distributed cache is configured Your job: 1. **Key on the lockfile, not the branch** — explain why `cache:key:files:` pointing at the lockfile (`package-lock.json`, `go.sum`, `poetry.lock`, `Gemfile.lock`) gives a key that changes only when dependencies change, and why keying on `$CI_COMMIT_REF_SLUG` alone wastes cache and risks staleness. 2. **Fallback keys** — show `fallback_keys` so a new branch warm-starts from the default branch's cache instead of installing from scratch, and explain the ordering. 3. **Cache the right paths** — per ecosystem, the directory to cache vs. the directory to NOT cache (e.g. cache the package-manager store, not `node_modules` if you use a content-addressed store; `.m2/repository`, `GOPATH/pkg/mod`, Poetry's virtualenvs, etc.). Get this exactly right. 4. **Policy** — set `policy: pull` on jobs that only consume the cache and `pull-push` only on the job that builds it, so parallel jobs don't race to overwrite the cache. 5. **Distributed cache requirement** — flag that on ephemeral/autoscaled runners, cache must be backed by S3/GCS or it's a no-op; local cache dies with the runner. 6. **Cache vs. lockfile install** — recommend the deterministic install command per manager (`npm ci`, `mvn -o` where viable, `go mod download`) and how cache interacts with it. 7. **Validation** — show how to read cache hit/miss from job logs and measure install time before/after. Output as: (a) per-ecosystem `cache:` block with `key:files:` + `fallback_keys` + correct paths + policy, (b) a hit/miss reading guide, (c) the distributed-cache prerequisite check, (d) the top causes of permanent cache misses, (e) before/after timing method. Bias toward: lockfile-based keys, pull-only consumers, distributed cache on ephemeral runners.