Skip to content

Getting started

View .md

Three steps: run the server, point the runners at it, run a workflow. No workflow file changes.

docker-compose.yml
services:
cache-server:
image: ghcr.io/falcondev-oss/github-actions-cache-server
restart: unless-stopped
ports:
- '3000:3000'
environment:
API_BASE_URL: http://cache-server.internal:3000
volumes:
- cache-data:/app/.data
volumes:
cache-data:

API_BASE_URL is the URL your runners use to reach the server. Replace cache-server.internal with a hostname or IP every runner can reach. The defaults store payloads on the filesystem and metadata in SQLite, both under /app/.data. All options are on the configuration page.

The image is a single static binary on distroless, about 29 MB. It has no shell, so health checks must probe GET /health over HTTP instead of running a command inside the container.

The chart is published as an OCI artifact. It needs Helm 3.8 or later.

Terminal window
helm install cache-server oci://ghcr.io/falcondev-oss/charts/github-actions-cache-server
kubectl get deployments,svc

The deployment cache-server-github-actions-cache-server serves on port 3000. Without config.apiBaseUrl the chart points runners at the internal service URL, which is what in-cluster runners need.

To customize, pass a values.yaml. All options are in the chart’s values.yaml.

Terminal window
helm install cache-server oci://ghcr.io/falcondev-oss/charts/github-actions-cache-server -f values.yaml

For runners managed by Actions Runner Controller, follow the ARC guide.

On SIGTERM the server stops accepting connections, finishes in-flight requests and running merges, then exits. Ingress controllers learn about a removed pod asynchronously, so add a preStop sleep to keep serving until they do. The image has no shell, so use the native sleep handler (Kubernetes 1.30+) and set a grace period longer than the sleep:

values.yaml
lifecycle:
preStop:
sleep:
seconds: 30
terminationGracePeriodSeconds: 60

The stock runner overwrites ACTIONS_RESULTS_URL with GitHub’s endpoint on every job. You need a runner that keeps your URL. How it works explains why.

Use our forked runner image and set CUSTOM_ACTIONS_RESULTS_URL:

image: ghcr.io/falcondev-oss/actions-runner:latest
env:
CUSTOM_ACTIONS_RESULTS_URL: http://cache-server.internal:3000/

The forked image skips runner self-update while CUSTOM_ACTIONS_RESULTS_URL is set, so a server-triggered update cannot silently replace the patched binary and send your caches back to GitHub. You still update it yourself, see keep the runner up to date.

If you build your own runner image, patch the binary so it overwrites a dummy variable instead of ACTIONS_RESULTS_URL. Then set ACTIONS_RESULTS_URL (with a trailing slash) on the runner.

Dockerfile
FROM ghcr.io/actions/actions-runner:latest
# Modify runner binary to retain custom ACTIONS_RESULTS_URL
RUN sed -i 's/\x41\x00\x43\x00\x54\x00\x49\x00\x4F\x00\x4E\x00\x53\x00\x5F\x00\x52\x00\x45\x00\x53\x00\x55\x00\x4C\x00\x54\x00\x53\x00\x5F\x00\x55\x00\x52\x00\x4C\x00/\x41\x00\x43\x00\x54\x00\x49\x00\x4F\x00\x4E\x00\x53\x00\x5F\x00\x52\x00\x45\x00\x53\x00\x55\x00\x4C\x00\x54\x00\x53\x00\x5F\x00\x4F\x00\x52\x00\x4C\x00/g' /home/runner/bin/Runner.Worker.dll
Linux
sed -i 's/\x41\x00\x43\x00\x54\x00\x49\x00\x4F\x00\x4E\x00\x53\x00\x5F\x00\x52\x00\x45\x00\x53\x00\x55\x00\x4C\x00\x54\x00\x53\x00\x5F\x00\x55\x00\x52\x00\x4C\x00/\x41\x00\x43\x00\x54\x00\x49\x00\x4F\x00\x4E\x00\x53\x00\x5F\x00\x52\x00\x45\x00\x53\x00\x55\x00\x4C\x00\x54\x00\x53\x00\x5F\x00\x4F\x00\x52\x00\x4C\x00/g' /path_to_your_runner/bin/Runner.Worker.dll
macOS
gsed -i 's/\x41\x00\x43\x00\x54\x00\x49\x00\x4F\x00\x4E\x00\x53\x00\x5F\x00\x52\x00\x45\x00\x53\x00\x55\x00\x4C\x00\x54\x00\x53\x00\x5F\x00\x55\x00\x52\x00\x4C\x00/\x41\x00\x43\x00\x54\x00\x49\x00\x4F\x00\x4E\x00\x53\x00\x5F\x00\x52\x00\x45\x00\x53\x00\x55\x00\x4C\x00\x54\x00\x53\x00\x5F\x00\x4F\x00\x52\x00\x4C\x00/g' /path_to_your_runner/bin/Runner.Worker.dll
Windows
[byte[]] -split (((Get-Content -Path ./bin/Runner.Worker.dll -Encoding Byte) | ForEach-Object ToString X2) -join '' -Replace '41004300540049004F004E0053005F0052004500530055004C00540053005F00550052004C00','41004300540049004F004E0053005F0052004500530055004C00540053005F004F0052004C00' -Replace '..', '0x$& ') | Set-Content -Path /path_to_your_runner/bin/Runner.Worker.dll -Encoding Byte

GitHub requires self-hosted runners to stay current. If a runner falls more than about 30 days behind the latest release, or below GitHub’s enforced minimum version, GitHub stops queuing jobs to it. Pull the latest forked runner image (or rebuild your patched image) and redeploy on a schedule.

Your workflows already use the server. Every actions/cache step, every setup-* action with cache: set and every BuildKit type=gha cache now reads and writes your server.

.github/workflows/ci.yml
jobs:
test:
runs-on: self-hosted
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
with:
node-version: 24
cache: npm # restored from your cache server
- run: npm ci

Confirm that requests reach your server with the checks in troubleshooting. A misconfigured runner falls back to GitHub’s cache without an error.