<img src="https://github.com/cloudbase/garm/raw/v0.2.1/doc/images/garm-light.svg#gh-light-mode-only" width="384px" alt="Light mode image" />
<img src="https://github.com/cloudbase/garm/raw/v0.2.1/doc/images/garm-dark.svg#gh-dark-mode-only" width="384px" alt="Dark mode image" />

GitHub Actions Runner Manager (GARM)

GARM is an open-source, self-hosted runner manager for GitHub Actions and Gitea Actions. It automatically creates, scales, and destroys ephemeral runner instances across multiple clouds and infrastructure providers from a single controller.

Highlights

• Multi-cloud from a single controller -- manage runners across AWS, Azure, GCP, OpenStack, OCI, LXD, Incus, Kubernetes, and more, all from one GARM instance. Mix and match providers freely.
• GitHub.com, GitHub Enterprise Server, and Gitea -- first-class support for all three forges.
• Pools and Scale Sets -- webhook-driven pools with configurable balancing (round-robin or bin-packing), plus native GitHub Actions Runner Scale Sets.
• Scale to zero -- create on-demand pools that only spin up runners when jobs are queued.
• Pluggable provider architecture -- providers are standalone executables. Use the 10+ existing providers or write your own in any language.
• Single binary, minimal dependencies -- no external database server, no message broker. GARM ships as one binary with an embedded SQLite database.
• Built-in web UI -- manage runners, pools, credentials, and endpoints from the browser.
• Kubernetes operator -- production-grade k8s integration via the GARM operator by @mercedes-benz.

Architecture

GARM supports two scaling modes:

Pools receive workflow_job webhooks from GitHub/Gitea, match jobs to pools by label, and create runners on demand. When multiple pools match, a configurable balancer (round-robin or pack) decides which pool handles the job.

Scale Sets use GitHub's native message queue. GitHub handles scheduling; GARM handles provisioning.

Architecture diagram (pools)

[!IMPORTANT] The README and documentation in the main branch are relevant to the not yet released code that is present in main. Following the documentation from the main branch for a stable release of GARM, may lead to errors. To view the documentation for the latest stable release, please switch to the appropriate tag. For information about setting up v0.2.0-beta1, please refer to the v0.2.0-beta1 tag.

[!CAUTION] The main branch holds the latest code and is not guaranteed to be stable. If you are looking for a stable release, please check the releases page. If you plan to use the main branch, please do so on a new instance. Do not upgrade from a stable release to main.

Getting started

Pick the quickstart that matches your setup:

• Quickstart: Docker -- deploy GARM as a Docker container (simplest)
• Quickstart: Systemd -- deploy GARM as a native Linux service
• First Steps -- add credentials, a repository, and your first runner pool

For Kubernetes deployments, see the GARM operator. To build from source, see Building from Source.

Documentation

Full documentation lives in the doc/ directory:

If you find the documentation lacking, please open an issue. Feedback from new users is especially valuable.

Supported providers

GARM uses external providers to create runners in a particular IaaS. Providers are standalone executables that GARM calls to manage runner instances.

Follow the instructions in each provider's README to install them.

Write your own provider

Providers are external executables that GARM calls to manage runner lifecycle in a given IaaS. They can be written in any language. See Writing an external provider for details.

Community

Whether you're running into issues or just want to drop by and say "hi", feel free to join us on Slack.