Getting Started - GitHub Actions Cache Server

The cache server is available as a Docker image and can be deployed via Docker Compose or Kubernetes.

1. Deploying the Cache Server

docker-compose.yml

services:
  cache-server:
    image: ghcr.io/falcondev-oss/github-actions-cache-server:latest
    ports:
      - '3000:3000'
    environment:
      API_BASE_URL: http://localhost:3000
    volumes:
      - cache-data:/app/.data

volumes:
  cache-data:

Environment Variables

`API_BASE_URL`

Example: http://localhost:3000

The base URL of your cache server. This needs to be accessible by your runners as it is used for making API requests and downloading cached files.

`STORAGE_DRIVER`

Default: filesystem

The storage driver to use for storing cache data. For more information, see Storage Drivers.

`DB_DRIVER`

Default sqlite

The database driver to use for storing cache metadata. For more information, see Database Drivers.

If set to true, will send a signed URL to the runner. The runner can then download the cache directly from the storage provider. This is useful if you have a large cache and don't want to proxy the download through the cache server.

The actions runner needs to be able to reach the storage provider directly to use direct downloads.

`CACHE_CLEANUP_OLDER_THAN_DAYS`

Default: 90

The number of days to keep stale cache data and metadata before deleting it. Set to 0 to disable cache cleanup.

`CACHE_CLEANUP_CRON`

Default: 0 0 * * *

The cron schedule for running the cache cleanup job.

`UPLOAD_CLEANUP_CRON`

Default: */10 * * * *

The cron schedule for running the upload cleanup job. This job will delete any dangling (failed or incomplete) uploads.

`NITRO_PORT`

Default: 3000

The port the server should listen on.

`TEMP_DIR`

Default: os temp dir

The directory to use for temporary files.

2. Setup with Self-Hosted Runners

Set the ACTIONS_RESULTS_URL on your runner to the API URL (with a trailing slash).

Ensure ACTIONS_RESULTS_URL ends with a trailing slash.

Runner Configuration

For Docker:

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

For Bare Metal, similar commands apply:

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

This patch prevents the runner from overwriting your custom ACTIONS_RESULTS_URL.

It is recommended to install zstd on your runners for faster compression and decompression.

3. Using the Cache Server

There is no need to change any of your workflows! 🔥

If you've set up your self-hosted runners correctly, they will automatically use the cache server for caching.

Storage Drivers

A list of storage drivers available for the GitHub Actions Cache Server