- Go 55.8%
- TypeScript 25.5%
- Svelte 16.9%
- Go Template 1.3%
- Shell 0.2%
- Other 0.1%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
e03045fc58
This change migrates from a pseudo pool ID composed of the entity ID and the name of the scale set, to a stable ID computed from the entity ID and the internal scaleset ID as an UUID V5. Both the entity ID and the internal scaleset ID are immutable. The UUID V5 will always be 36 characters long, regardless of the input data used to compute it. The downside of this change is that we now need to do two ListInstance() provider calls to list both instances tagged with the old shape of the ID and the new shape. Internally we record whether or not ListInstances() returned an empty list. If empty, we don't have instances in the provider for a scale set, so on each subsequent list, we only do one call. So in theory at least, we should only be abusing the IaaS API only as long as there are still old runners tagged with the old shape. Signed-off-by: Gabriel Adrian Samfira <gsamfira@cloudbasesolutions.com> |
||
| .github | ||
| apiserver | ||
| auth | ||
| cache | ||
| client | ||
| cmd | ||
| config | ||
| contrib | ||
| database | ||
| doc | ||
| internal | ||
| locking | ||
| metrics | ||
| params | ||
| runner | ||
| scripts | ||
| test/integration | ||
| testdata | ||
| util | ||
| vendor | ||
| webapp | ||
| websocket | ||
| workers | ||
| .dockerignore | ||
| .gitignore | ||
| .golangci.yml | ||
| .mockery.yaml | ||
| Dockerfile | ||
| Dockerfile.build-static | ||
| go.mod | ||
| go.sum | ||
| LICENSE | ||
| Makefile | ||
| README.md | ||
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
mainbranch are relevant to the not yet released code that is present inmain. Following the documentation from themainbranch 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 upv0.2.0-beta1, please refer to the v0.2.0-beta1 tag.
Caution
The
mainbranch 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 themainbranch, please do so on a new instance. Do not upgrade from a stable release tomain.
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:
| Section | Guides |
|---|---|
| Setup | Credentials · Configuration · Webhooks |
| Usage | Managing Entities · Pools and Scaling · Scale Sets |
| Advanced | Templates · Providers · Gitea · Agent and Object Store |
| Operations | Monitoring · Performance · FAQ |
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.
| Provider | Repository |
|---|---|
| Akamai/Linode | flatcar/garm-provider-linode (experimental) |
| Amazon EC2 | cloudbase/garm-provider-aws |
| Azure | cloudbase/garm-provider-azure |
| CloudStack | nexthop-ai/garm-provider-cloudstack |
| GCP | cloudbase/garm-provider-gcp |
| Incus | cloudbase/garm-provider-incus |
| Kubernetes | mercedes-benz/garm-provider-k8s |
| LXD | cloudbase/garm-provider-lxd |
| OpenStack | cloudbase/garm-provider-openstack |
| Oracle OCI | cloudbase/garm-provider-oci |
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.