cacheport

CI provider

Cacheport with GitLab CI

GitLab jobs run in fresh containers, often on autoscaled runners that start empty. Cacheport gives every job the same warm cache for packages and job images, whatever runner picks it up.

CI · GITLAB-CIManifest
Config
.gitlab-ci.yml
Token
Masked CI/CD variable CACHEPORT_TOKEN
Keyless
id_tokens with aud: https://cacheport.cc
Job images
DOCKER_AUTH_CONFIG for the Docker Hub cache
Runner cache
S3-compatible, see CI Cache

Give your pipelines a token

Option 1: a masked variable

Add CACHEPORT_TOKEN as a masked, protected variable at group level so every project inherits it.

shell
$ cacheport token create gitlab-ci --scope read
# GitLab: Group > Settings > CI/CD > Variables
# Key: CACHEPORT_TOKEN  Masked: yes  Protected: yes
Option 2: OIDC ID tokens

Request an ID token in the job and exchange it for a short-lived Cacheport token.

.gitlab-ci.yml
test:
  id_tokens:
    CACHEPORT_ID_TOKEN:
      aud: https://cacheport.cc
  before_script:
    - export CACHEPORT_TOKEN=$(curl -s -X POST https://cacheport.cc/api/oidc/exchange -d "workspace=acme&token=$CACHEPORT_ID_TOKEN")

Examples

Pick an ecosystem. Every example uses the CACHEPORT_TOKEN secret from above.

npm

.gitlab-ci.yml
test:
  image: node:22
  before_script:
    - echo "registry=https://acme.cacheport.cc/npm/" > .npmrc
    - echo "//acme.cacheport.cc/npm/:_authToken=${CACHEPORT_TOKEN}" >> .npmrc
  script:
    - npm ci
    - npm test

Full guide: npm cache.

Yarn

.gitlab-ci.yml
test:
  image: node:22
  variables:
    YARN_NPM_REGISTRY_SERVER: https://acme.cacheport.cc/npm/
  script:
    - corepack enable
    - export YARN_NPM_AUTH_TOKEN="$CACHEPORT_TOKEN"
    - yarn install --immutable
    - yarn test

Full guide: Yarn cache.

pnpm

.gitlab-ci.yml
test:
  image: node:22
  before_script:
    - corepack enable
    - pnpm config set store-dir .pnpm-store
  script:
    - pnpm install --frozen-lockfile
    - pnpm test
  cache:
    key:
      files: [pnpm-lock.yaml]
    paths: [.pnpm-store]

Full guide: pnpm cache.

pip

.gitlab-ci.yml
test:
  image: python:3.13
  script:
    - export PIP_INDEX_URL="https://ci:${CACHEPORT_TOKEN}@acme.cacheport.cc/pypi/simple/"
    - pip install -r requirements.txt
    - pytest

Full guide: pip cache.

Poetry

.gitlab-ci.yml
test:
  image: python:3.13
  variables:
    POETRY_HTTP_BASIC_CACHEPORT_USERNAME: ci
  script:
    - export POETRY_HTTP_BASIC_CACHEPORT_PASSWORD="$CACHEPORT_TOKEN"
    - pip install poetry
    - poetry install --no-interaction
    - poetry run pytest

Full guide: Poetry cache.

uv

.gitlab-ci.yml
test:
  image: ghcr.io/astral-sh/uv:python3.13-bookworm
  variables:
    UV_INDEX_CACHEPORT_USERNAME: ci
  script:
    - export UV_INDEX_CACHEPORT_PASSWORD="$CACHEPORT_TOKEN"
    - uv sync --locked
    - uv run pytest

Full guide: uv cache.

Conda

.gitlab-ci.yml
test:
  image: condaforge/miniforge3
  script:
    - export CONDA_CHANNEL_ALIAS="https://ci:${CACHEPORT_TOKEN}@acme.cacheport.cc/conda/"
    - conda env create -f environment.yml -n ci
    - conda run -n ci pytest

Full guide: Conda cache.

Maven

.gitlab-ci.yml
build:
  image: maven:3.9-eclipse-temurin-21
  script:
    - mvn verify
  cache:
    key: maven
    paths: [.m2/repository]
  variables:
    MAVEN_OPTS: "-Dmaven.repo.local=$CI_PROJECT_DIR/.m2/repository"

Full guide: Maven cache.

Gradle

.gitlab-ci.yml
build:
  image: eclipse-temurin:21
  variables:
    GRADLE_USER_HOME: $CI_PROJECT_DIR/.gradle-home
  script:
    - ./gradlew build
  cache:
    key: gradle
    paths: [.gradle-home/wrapper]

Full guide: Gradle cache.

Go modules

.gitlab-ci.yml
test:
  image: golang:1.23
  variables:
    GOPROXY: https://acme.cacheport.cc/go,direct
  before_script:
    - printf "machine acme.cacheport.cc login ci password %s\n" "$CACHEPORT_TOKEN" > ~/.netrc
  script:
    - go test ./...

Full guide: Go modules cache.

Cargo

.gitlab-ci.yml
test:
  image: rust:1
  script:
    - export CARGO_REGISTRIES_CACHEPORT_TOKEN="Bearer $CACHEPORT_TOKEN"
    - cargo test --locked

Full guide: Cargo cache.

RubyGems

.gitlab-ci.yml
test:
  image: ruby:3.3
  before_script:
    - bundle config set --global mirror.https://rubygems.org https://acme.cacheport.cc/gems/
    - bundle config set --global acme.cacheport.cc "ci:$CACHEPORT_TOKEN"
  script:
    - bundle install
    - bundle exec rake test

Full guide: RubyGems cache.

Composer

.gitlab-ci.yml
test:
  image: composer:2
  script:
    - export COMPOSER_AUTH="{\"http-basic\":{\"acme.cacheport.cc\":{\"username\":\"ci\",\"password\":\"$CACHEPORT_TOKEN\"}}}"
    - composer install --no-interaction --prefer-dist
    - vendor/bin/phpunit

Full guide: Composer cache.

NuGet

.gitlab-ci.yml
build:
  image: mcr.microsoft.com/dotnet/sdk:8.0
  script:
    - dotnet restore --locked-mode
    - dotnet test --no-restore

Full guide: NuGet cache.

Docker Hub

.gitlab-ci.yml
test:
  image: acme.cacheport.cc/hub/library/node:22-alpine
  variables:
    DOCKER_AUTH_CONFIG: $CACHEPORT_DOCKER_AUTH
  script:
    - npm ci
    - npm test

Full guide: Docker Hub cache.

Helm

.gitlab-ci.yml
deploy:
  image: alpine/helm:3
  script:
    - helm repo add prometheus-community https://acme.cacheport.cc/helm/prometheus-community/ --username ci --password "$CACHEPORT_TOKEN"
    - helm dependency build charts/app

Full guide: Helm cache.

apt

.gitlab-ci.yml
test:
  image: debian:bookworm-slim
  before_script:
    - sed -i "s|http://deb.debian.org|http://acme.cacheport.cc/apt/deb.debian.org|g" /etc/apt/sources.list.d/debian.sources
    - apt-get update && apt-get install -y --no-install-recommends make gcc
  script:
    - make test

Full guide: apt cache.

Alpine apk

.gitlab-ci.yml
test:
  image: alpine:3.20
  before_script:
    - sed -i "s|https://dl-cdn.alpinelinux.org|https://acme.cacheport.cc/apk|g" /etc/apk/repositories
    - apk add --no-cache make gcc musl-dev
  script:
    - make test

Full guide: Alpine apk cache.

Job images from the cache

Runners pull the job image before your script runs. To pull it through the Docker Hub cache, set image: acme.cacheport.cc/hub/library/node:22 and provide credentials with a DOCKER_AUTH_CONFIG variable containing an auths entry for acme.cacheport.cc.

Distributed runner cache

The cache: keyword stores folders in the runner's cache backend. For autoscaled runners, point that backend at CI Cache, which speaks the S3 protocol GitLab Runner expects.

Questions

Does it work on GitLab.com shared runners?

Yes. Shared runners can reach Cacheport over HTTPS like any other host.

What about self-managed GitLab behind a firewall?

Allow outbound HTTPS to acme.cacheport.cc. Enterprise plans can also get dedicated nodes inside your network.

Can I use GitLab's dependency proxy as well?

You can, but you will not need it for Docker Hub: Cacheport covers it and other registries with the same token.

Setting up somewhere else too?

Start on the free plan

20 GB of cache, every registry, unlimited users. Upgrade when your pipelines outgrow it.