Skip to content
Start free
Documentation menu

CI cache

The CI cache stores directories as content-addressed chunks. Saving uploads only chunks the registry does not already hold, and restoring downloads only chunks the runner does not already have.

Save and restore

terminal
$ qln cache restore --key "gradle-$(sha256sum gradle.lockfile | cut -c1-16)" \
    --fallback gradle- ~/.gradle/caches
restored 2.4 GB (rank: exact) in 8.1 s from eu-central-1

$ ./gradlew build

$ qln cache save --key "gradle-$(sha256sum gradle.lockfile | cut -c1-16)" ~/.gradle/caches
saved: 7 of 603 chunks new, uploaded 58 MB in 1.9 s

Restore tries the exact key first, then each --fallback prefix from newest to oldest. A saved entry is immutable; to refresh it, change the key.

GitHub Actions

build.yml
# .github/workflows/build.yml
jobs:
  build:
    runs-on: ubuntu-24.04
    permissions: { id-token: write, contents: read }
    steps:
      - uses: actions/checkout@v4
      - name: Sign in to Quayline with OIDC
        run: qln login --oidc --org tidewater --audience quayline
      - name: Restore cache
        run: qln cache restore --key "pnpm-${{ hashFiles('pnpm-lock.yaml') }}" --fallback pnpm- node_modules
      - run: pnpm install --frozen-lockfile && pnpm build
      - name: Save cache
        if: success()
        run: qln cache save --key "pnpm-${{ hashFiles('pnpm-lock.yaml') }}" node_modules

GitLab CI

.gitlab-ci.yml
# .gitlab-ci.yml
build:
  image: fi4.enotcloud.com/tidewater/ci-base:2026.11
  id_tokens:
    QLN_ID_TOKEN: { aud: quayline }
  script:
    - qln login --oidc-token "$QLN_ID_TOKEN" --org tidewater
    - qln cache restore --key "mvn-$CI_COMMIT_REF_SLUG" --fallback mvn-main .m2/repository
    - mvn -B verify
    - qln cache save --key "mvn-$CI_COMMIT_REF_SLUG" .m2/repository

Scopes and isolation

Entries are scoped to the repository that wrote them. A branch can read entries saved by the default branch but not entries from other branches, which stops a pull request from poisoning the cache that releases use. Set --scope org to share an entry between repositories deliberately.

Eviction

  • Entries unused for 14 days are removed. The default is configurable per organisation from 1 to 90 days.
  • Each entry may be up to 40 GB. Cache storage counts toward your storage pool at half weight.
  • When a repository exceeds 500 GB of cache, the least recently restored entries go first.

What is metered

Restores to a runner in the same region as the storage cell are free and do not touch your egress pool. Cross-region restores count as egress. Check qln usage --cache to see the split.