Welcome to garm!
Garm enables you to create and automatically maintain pools of self-hosted GitHub runners, with autoscaling that can be used inside your github workflow runs.
The goal of garm is to be simple to set up, simple to configure and simple to use. It is a single binary that can run on any GNU/Linux machine without any other requirements other than the providers it creates the runners in. It is intended to be easy to deploy in any environment and can create runners in any system you can write a provider for. There is no complicated setup process and no extremely complex concepts to understant. Once set up, it's meant to stay out of your way.
You need to have Go install, then run:
git clone https://github.com/cloudbase/garm
cd garm
go install ./...You should now have both garm and garm-cli in your $GOPATH/bin folder.
If you have docker/podman installed, you can also build statically linked binaries by running:
makeThe garm and garm-cli binaries will be built and copied to the bin/ folder in your current working directory.
Add a new system user:
useradd --shell /usr/bin/false \
--system \
--groups lxd \
--no-create-home garmThe lxd group is only needed if you have a local LXD install and want to connect to the unix socket to use it. If you're connecting to a remote LXD server over TCP, you can skip adding the garm user to the lxd group.
Copy the binary to somewhere in the system $PATH:
sudo cp $(go env GOPATH)/bin/garm /usr/local/bin/garmOr if you built garm using make:
sudo cp ./bin/garm /usr/local/bin/garmCreate the config folder:
sudo mkdir -p /etc/garmCopy the config template:
sudo cp ./testdata/config.toml /etc/garm/Copy the external provider (optional):
sudo cp -a ./contrib/providers.d /etc/garm/Copy the systemd service file:
sudo cp ./contrib/garm.service /etc/systemd/system/Change permissions on config folder:
sudo chown -R garm:garm /etc/garm
sudo chmod 750 -R /etc/garmEnable the service:
sudo systemctl enable garmCustomize the config in /etc/garm/config.toml, and start the service:
sudo systemctl start garmThe garm configuration is a simple toml. A sample of the config file can be found in the testdata folder.
There are 3 major sections of the config that require your attention:
Once you've configured your database, providers and github credentials, you'll need to configure your webhooks and the callback_url.
At this point, you should be done. Have a look at the running garm document for usage instructions and available features.
If you would like to use garm with a different IaaS than the ones already available, have a loot at the writing an external provider page.
Garm does not apply any ACLs of any kind to the instances it creates. That task remains in the responsability of the user. Here is a guide for creating ACLs in LXD. You can of course use iptables or nftables to create any rules you wish. I recommend you create a separate isolated lxd bridge for runners, and secure it using ACLs/iptables/nftables.
You must make sure that the code that runs as part of the workflows is trusted, and if that cannot be done, you must make sure that any malitious code that will be pulled in by the actions and run as part of a workload, is as contained as possible. There is a nice article about securing your workflow runs here.
The providers are interfaces between garm and a particular IaaS in which we spin up GitHub Runners. These providers can be either native or external. The native providers are written in Go, and must implement the interface defined here. External providers can be written in any language, as they are in the form of an external executable that garm calls into.
There is currently one native provider for LXD and two external providers for Openstack and Azure.
If you want to write your own provider, you can choose to write a native one, or implement an external one. The easiest one to write is probably an external provider. Please see the Writing an external provider document for details. Also, feel free to inspect the two available external providers in this repository.