Getting Started

The cache server comes as a Docker image and can be deployed using Docker Compose or Kubernetes.

1. Deploying the Cache Server

version: '3.9'

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

volumes:
  cache-data:

Environment Variables

URL_ACCESS_TOKEN

This token is used to authenticate runtime requests to the cache server. It should be a long random string. It is part of the URL used to access the cache server because we cannot use cookies or headers for authentication.

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.

ENABLE_DIRECT_DOWNLOADS

• Default: false

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.

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.

NITRO_PORT

• Default: 3000

The port the server should listen on.

2. Setup with Self-Hosted Runners

To leverage the GitHub Actions Cache Server with your self-hosted runners, you'll need to configure a couple of environment variables on your runners. This ensures that your runners can authenticate with and utilize the cache server effectively.

Configuring Environment Variables on Self-Hosted Runners

ACTIONS_CACHE_URL: This tells your self-hosted runner where to send cache requests. Set this environment variable to the API_BASE_URL of your cache server with the URL_ACCESS_TOKEN as first path parameter, making sure to include a trailing slash.

For example, if your cache server's API_BASE_URL is http://localhost:3000 and your URL_ACCESS_TOKEN is random_token, you would set ACTIONS_CACHE_URL to http://localhost:3000/random_token/.

Getting the Actions Runner to Use the Cache Server

The default self-hosted runner overwrites the ACTIONS_CACHE_URL environment variable with the GitHub-hosted cache server URL. To get the runner to use your self-hosted cache server, you'll need to modify the runner binary:

Docker

Just add the following lines to your Dockerfile:

FROM ghcr.io/actions/actions-runner:latest

# modify actions runner binaries to allow custom cache server implementation
RUN sed -i 's/\x41\x00\x43\x00\x54\x00\x49\x00\x4F\x00\x4E\x00\x53\x00\x5F\x00\x43\x00\x41\x00\x43\x00\x48\x00\x45\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\x43\x00\x41\x00\x43\x00\x48\x00\x45\x00\x5F\x00\x4F\x00\x52\x00\x4C\x00/g' /home/runner/bin/Runner.Worker.dll

Bare Metal

sed -i 's/\x41\x00\x43\x00\x54\x00\x49\x00\x4F\x00\x4E\x00\x53\x00\x5F\x00\x43\x00\x41\x00\x43\x00\x48\x00\x45\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\x43\x00\x41\x00\x43\x00\x48\x00\x45\x00\x5F\x00\x4F\x00\x52\x00\x4C\x00/g' /path_to_your_runner/bin/Runner.Worker.dll

This will replace the strings ACTIONS_CACHE_URL with ACTIONS_CACHE_ORL in the runner binary. This will prevent the runner from overwriting the ACTIONS_CACHE_URL environment variable and allow it to use your self-hosted cache server.

Doing it this way is a bit of a hack, but it's easier than compiling your own runner binary from source and works great.

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.