GARM (GitHub Actions Runner Manager) automatically creates and manages self-hosted GitHub Actions runners across multiple infrastructure providers. It supports GitHub.com, GitHub Enterprise Server, and Gitea.
Get GARM running and create your first runner pool:
- 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
| Guide | Description |
|---|
| Credentials | PATs, GitHub Apps, Gitea tokens, and required permissions |
| Managing Entities | Repositories, organizations, enterprises, endpoints, and webhooks |
| Pools and Scaling | Pool configuration, scaling behavior, balancing, labels, and runner management |
| Scale Sets | GitHub scale sets as an alternative to webhook-driven pools |
| Templates | Customizing runner bootstrap scripts |
| Using GARM with Gitea | Gitea-specific setup and differences from GitHub |
| Agent Mode and Object Store | WebSocket agent mode, remote shell, file storage |
GitHub/Gitea GARM Provider (LXD, AWS, etc.)
| | |
|-- webhook: job queued -------->| |
| |-- create instance ------------>|
| | |-- boots VM/container
| |<-- instance ready -------------|
| | |
|<-- runner registers -----------| |
| | |
|-- job runs on runner --------->| |
| | |
|-- webhook: job completed ----->| |
| |-- delete instance ------------>|
| | |
- GitHub sends a
workflow_job webhook when a job is queued (or GARM polls a scale set message queue)
- GARM finds a matching pool and asks the provider to create an instance
- The instance boots, installs the runner, and registers with GitHub
- The runner picks up the job and executes it
- When the job completes, GARM deletes the instance
| Concept | Description |
|---|
| Controller | A GARM installation, identified by a unique Controller ID |
| Endpoint | A GitHub.com, GHES, or Gitea server that GARM connects to |
| Credential | A PAT or GitHub App tied to an endpoint, used to manage runners |
| Entity | A repository, organization, or enterprise managed by GARM |
| Provider | An external executable that creates/destroys infrastructure (LXD, AWS, etc.) |
| Pool | A group of runners with the same config (image, flavor, labels, provider) |
| Scale Set | An alternative to pools using GitHub's message queue instead of webhooks |
| Runner | A self-hosted GitHub/Gitea runner instance |
| Template | A script that customizes how runners are bootstrapped |