Name: github-actions-cache-server
Availability: InStock
Author: falcondev-oss

GitHub Website

HelmFull install guide

$ helm install <release-name> oci://ghcr.io/falcondev-oss/charts/github-actions-cache-server

Updated6 hours ago

LanguageRust

Setup difficultyModerate

Stars: 459
Port: 3000 (HTTP server listening port (default of NITRO_PORT))

Docker

ghcr.io/falcondev-oss/github-actions-cache-server

What is github-actions-cache-server?

The GitHub Actions Cache Server is a reimplementation of GitHub's hosted Actions cache service that runs on your own infrastructure. Because it speaks the same cache API, the official actions/cache action and packages that use it internally keep working with no workflow edits — only the self-hosted runner needs its ACTIONS_RESULTS_URL pointed at the cache server, either via a patched runner binary or the project's forked runner image. Cache payloads can live on the local filesystem, S3-compatible buckets, Google Cloud Storage or Azure Blob Storage, while metadata is kept in PostgreSQL, MySQL or SQLite. Notable capabilities include signed direct-download URLs that bypass the server, eager merging of cache parts inside the bucket, automatic cleanup of stale entries, LRU eviction against a size budget, a Prometheus metrics endpoint, an optional management API, and transparent forwarding of non-cache requests to GitHub's Results service. It is deployed as a single container (Docker Compose) or through a Helm chart. GitHub Enterprise Server also works, though the project treats that as best-effort and implements only the v2 cache protocol, so legacy v1 caching will not function. The project is MIT-licensed and under active development.

Should you self-host github-actions-cache-server?

github-actions-cache-server scores 49/100 on selfhost.directory (how scoring works) and ranks #22 of 28 in CI/CD. It has 459 GitHub stars.

It shipped 19 stable releases in the past year. The latest, v10.0.0, came out on 28 October 2026. New versions land roughly every 5 days.

Setup is moderate: expect some configuration beyond a single command. An official Docker image is available. It is MIT-licensed and written mostly in Rust.

Its closest alternative on selfhost.directory is jenkins (82/100, 26 704 stars). It scores higher overall, so compare the two before you pick. See github-actions-cache-server vs jenkins side by side.

Features

Automatic stale cache cleanup
Cache API compatible with actions/cache
Cache size cap with LRU eviction
Direct downloads via signed URLs
Eager merge of cache parts
GitHub Enterprise Server supportBest-effort; only the v2 cache protocol is implemented.
Management API
Multiple database driversSQLite is discouraged for production.
Multiple Storage Drivers
Prometheus MetricsEndpoint is unauthenticated; restrict at the network layer.
Results service passthrough
Runner token verification via OIDC

How to configure github-actions-cache-server

ACTIONS_TOKEN_ISSUERhttps://token.actions.githubusercontent.comOIDC issuer whose signature the cache server verifies on runner tokens; must match the iss claim exactly.
OIDC issuer whose signature the cache server verifies on runner tokens; must match the iss claim exactly.
ACTIONS_TOKEN_JWKS_URLExplicit JWKS endpoint, skipping OIDC discovery.
Explicit JWKS endpoint, skipping OIDC discovery.
API_BASE_URLBase URL of the cache server; must be reachable by runners for cache uploads and downloads.
Base URL of the cache server; must be reachable by runners for cache uploads and downloads.
AWS_ACCESS_KEY_IDAccess key for authenticating with S3-compatible storage.
Access key for authenticating with S3-compatible storage.
AWS_ENDPOINT_URLEndpoint URL for non-AWS S3-compatible storage, e.g. http://rustfs:9000.
Endpoint URL for non-AWS S3-compatible storage, e.g. http://rustfs:9000.
AWS_PROFILEName of an AWS credentials/CLI profile to use (requires mounting the credentials file).
Name of an AWS credentials/CLI profile to use (requires mounting the credentials file).
AWS_REGIONus-east-1AWS region used by the AWS SDK; no effect on non-AWS S3-compatible providers.
AWS region used by the AWS SDK; no effect on non-AWS S3-compatible providers.
AWS_REQUEST_CHECKSUM_CALCULATIONAWS SDK checksum setting; docs suggest WHEN_REQUIRED for S3-compatible backends like Garage that compute multipart checksums differently.
AWS SDK checksum setting; docs suggest WHEN_REQUIRED for S3-compatible backends like Garage that compute multipart checksums differently.
values: WHEN_REQUIRED
AWS_RESPONSE_CHECKSUM_VALIDATIONAWS SDK checksum validation setting; docs suggest WHEN_REQUIRED for problematic S3-compatible backends.
AWS SDK checksum validation setting; docs suggest WHEN_REQUIRED for problematic S3-compatible backends.
values: WHEN_REQUIRED
AWS_SECRET_ACCESS_KEYSecret key for authenticating with S3-compatible storage.
Secret key for authenticating with S3-compatible storage.
CACHE_CLEANUP_OLDER_THAN_DAYS90Days to keep stale cache data and metadata before deleting it; 0 disables cleanup.
Days to keep stale cache data and metadata before deleting it; 0 disables cleanup.
CACHE_FILESYSTEM_MAX_USAGE_PERCENT90Max percentage of the storage volume that may be used before eviction starts (filesystem driver only, when CACHE_MAX_SIZE_BYTES is unset).
Max percentage of the storage volume that may be used before eviction starts (filesystem driver only, when CACHE_MAX_SIZE_BYTES is unset).
CACHE_MAX_SIZE_BYTESHard cap in bytes on total finalized cache payload size; triggers LRU eviction down to 90% of the budget.
Hard cap in bytes on total finalized cache payload size; triggers LRU eviction down to 90% of the budget.
DB_DRIVERsqliteThe database driver to use for storing cache metadata.
The database driver to use for storing cache metadata.
values: sqlite, postgres, mysql
DB_MYSQL_DATABASEThe name of the MySQL database to use.
The name of the MySQL database to use.
DB_MYSQL_HOSTThe host of the MySQL database.
The host of the MySQL database.
DB_MYSQL_PASSWORDThe password to authenticate with the MySQL database.
The password to authenticate with the MySQL database.
DB_MYSQL_PORTThe port of the MySQL database.
The port of the MySQL database.
DB_MYSQL_USERThe user to authenticate with the MySQL database.
The user to authenticate with the MySQL database.
DB_POSTGRES_DATABASEThe name of the PostgreSQL database to use.
The name of the PostgreSQL database to use.
DB_POSTGRES_HOSTThe host of the PostgreSQL database.
The host of the PostgreSQL database.
DB_POSTGRES_PASSWORDThe password to authenticate with the PostgreSQL database.
The password to authenticate with the PostgreSQL database.
DB_POSTGRES_PORTThe port of the PostgreSQL database.
The port of the PostgreSQL database.
DB_POSTGRES_URLFull URL to the PostgreSQL database; alternative to the individual options.
Full URL to the PostgreSQL database; alternative to the individual options.
DB_POSTGRES_USERThe user to authenticate with the PostgreSQL database.
The user to authenticate with the PostgreSQL database.
DB_SQLITE_PATH.data/sqlite.dbPath to the SQLite database file; created if it does not exist.
Path to the SQLite database file; created if it does not exist.
DEFAULT_ACTIONS_RESULTS_URLhttps://results-receiver.actions.githubusercontent.comUpstream GitHub Actions Results service that unhandled requests are transparently forwarded to.
Upstream GitHub Actions Results service that unhandled requests are transparently forwarded to.
EAGER_MERGEfalseStarts merging cache parts right after upload completes, instead of on first download.
Starts merging cache parts right after upload completes, instead of on first download.
values: true, false
ENABLE_DIRECT_DOWNLOADSfalseIf true, sends a signed URL to the runner so it downloads the cache directly from the storage provider.
If true, sends a signed URL to the runner so it downloads the cache directly from the storage provider.
values: true, false
MANAGEMENT_API_KEYSet to a random string to enable the management API.
Set to a random string to enable the management API.
NITRO_PORT3000The port the server should listen on.
The port the server should listen on.
SKIP_TOKEN_VALIDATIONfalseSkip verification of the GitHub token used for computing the cache scope; for testing only.
Skip verification of the GitHub token used for computing the cache scope; for testing only.
values: true, false
STORAGE_AZBLOB_ACCOUNTStorage account name for Entra ID / DefaultAzureCredential authentication.
Storage account name for Entra ID / DefaultAzureCredential authentication.
STORAGE_AZBLOB_CONNECTION_STRINGStorage account connection string with a shared key; mutually exclusive with STORAGE_AZBLOB_ACCOUNT/ENDPOINT.
Storage account connection string with a shared key; mutually exclusive with STORAGE_AZBLOB_ACCOUNT/ENDPOINT.
STORAGE_AZBLOB_CONTAINERName of the blob container used for storage; always required for the azblob driver.
Name of the blob container used for storage; always required for the azblob driver.
STORAGE_AZBLOB_ENDPOINTBlob service endpoint; defaults to https://<account>.blob.core.windows.net.
Blob service endpoint; defaults to https://<account>.blob.core.windows.net.
STORAGE_DRIVERfilesystemThe storage driver to use for storing cache data.
The storage driver to use for storing cache data.
values: filesystem, s3, gcs, azblob
STORAGE_FILESYSTEM_PATH.data/storage/filesystemPath to the filesystem storage location; created if missing.
Path to the filesystem storage location; created if missing.
STORAGE_GCS_BUCKETName of the GCS bucket used for storage.
Name of the GCS bucket used for storage.
STORAGE_GCS_ENDPOINTThe API endpoint for GCS.
The API endpoint for GCS.
STORAGE_GCS_SERVICE_ACCOUNT_KEYPath to the service account key used for authentication; falls back to Application Default Credentials if unset.
Path to the service account key used for authentication; falls back to Application Default Credentials if unset.
STORAGE_S3_BUCKETName of the S3 bucket used for storage; always required for the s3 driver.
Name of the S3 bucket used for storage; always required for the s3 driver.