Cattery

Cattery is a scheduler and lifecycle manager for GitHub Actions self-hosted runners. It dynamically provisions ephemeral runner instances across multiple infrastructure providers in response to workflow job demand using GitHub's runner scale sets API.

How it works

Cattery follows a server/agent architecture:

GitHub Actions Cattery Server Infrastructure
(Scale Set API) | (Docker / GCE)
| | |
|-- job demand ----------->| |
| |-- provision tray ----------->|
| | |
| |<-- agent registers ---------|
|<-- JIT runner config ----| |
| | |
|-- job started ---------->|-- assign job to tray ------->|
|-- job completed -------->|-- delete tray -------------->|

Server polls GitHub for pending jobs via the scale set API, provisions runner instances ("trays") through configured providers, and manages their full lifecycle. Each tray is an ephemeral runner — created on demand, used for a single job, then destroyed.

Agent runs inside each provisioned instance. It registers with the server to receive a JIT runner configuration, starts the GitHub Actions runner, monitors the job, and reports back when done.

Tray lifecycle

A tray progresses through: Creating -> Registering -> Registered -> Running -> Deleting

Stale trays (no heartbeat for 2+ minutes) are automatically cleaned up.

Features

• Multi-provider — Ships with Docker and Google Compute Engine providers, new providers can be added
• Scale-to-zero — Runners are only provisioned when jobs are queued
• Ephemeral runners — Each job gets a fresh, isolated environment via JIT configuration
• Multi-org support — Manage runners across multiple GitHub organizations from a single server
• Automatic failed job restart — Agents can request reruns of failed workflow jobs
• Monitoring — Built-in status page (/status) and Prometheus metrics (/metrics)

Prerequisites

• Go 1.25+
• MongoDB
• A GitHub App with Actions read/write and Pull requests read permissions, installed on your organization
• Docker and/or GCP credentials depending on your provider choice

Quick start

Build

cd src
go build -o cattery

Or with Docker:

docker build --build-arg CATTERY_VERSION=0.1.0 -t cattery .

Configure

Create a config.yaml (see Configuration for full reference):

server:
listenAddress: "0.0.0.0:5137"advertiseUrl: https://cattery.example.comdatabase:
uri: mongodb://localhost:27017/database: catterygithub:
- name: my-orgappId: 123456appClientId: Iv123abCinstallationId: 987654321privateKeyPath: /path/to/private-key.pemproviders:
- name: docker-localtype: dockertrayTypes:
- name: my-runnerprovider: docker-localgithubOrg: my-orgrunnerGroupId: 1maxTrays: 5config:
image: my-runner-image:latest

Run

Server:

./cattery server -c /path/to/config.yaml

Agent (runs inside provisioned instances):

./cattery agent \
--runner-folder /path/to/actions-runner \
--server-url http://cattery-server:5137 \
--agent-id <tray-id>

Install with Helm

The chart is published to a Helm repository hosted on GitHub Pages:

helm repo add cattery https://paritytech.github.io/cattery
helm repo update
helm install cattery cattery/cattery

Override defaults with your own values:

helm install cattery cattery/cattery -f my-values.yaml

See charts/cattery/values.yaml for the available values.

Configuration

See docs/configuration.md for the full configuration reference covering server, database, GitHub App, providers, and tray types.

License

MIT