The default config section holds configuration options that don't need a category of their own, but are essential to the operation of the service. In this section we will detail each of the options available in the default section.
[default]
# This URL is used by instances to send back status messages as they install
# the github actions runner. Status messages can be seen by querying the
# runner status in garm.
# Note: If you're using a reverse proxy in front of your garm installation,
# this URL needs to point to the address of the reverse proxy. Using TLS is
# highly encouraged.
callback_url = "https://garm.example.com/api/v1/callbacks"
# This URL is used by instances to retrieve information they need to set themselves
# up. Access to this URL is granted using the same JWT token used to send back
# status updates. Once the instance transitions to "installed" or "failed" state,
# access to both the status and metadata endpoints is disabled.
# Note: If you're using a reverse proxy in front of your garm installation,
# this URL needs to point to the address of the reverse proxy. Using TLS is
# highly encouraged.
metadata_url = "https://garm.example.com/api/v1/metadata"
# Uncomment this line if you'd like to log to a file instead of standard output.
# log_file = "/tmp/runner-manager.log"
# Enable streaming logs via web sockets. Use garm-cli debug-log.
enable_log_streamer = false
# Enable the golang debug server. See the documentation in the "doc" folder for more information.
debug_server = falseYour runners will call back home with status updates as they install. Once they are set up, they will also send the GitHub agent ID they were allocated. You will need to configure the callback_url option in the garm server config. This URL needs to point to the following API endpoint:
POST /api/v1/callbacks/statusExample of a runner sending status updates:
garm-cli runner show garm-DvxiVAlfHeE7
+-----------------+------------------------------------------------------------------------------------+
| FIELD | VALUE |
+-----------------+------------------------------------------------------------------------------------+
| ID | 16b96ba2-d406-45b8-ab66-b70be6237b4e |
| Provider ID | garm-DvxiVAlfHeE7 |
| Name | garm-DvxiVAlfHeE7 |
| OS Type | linux |
| OS Architecture | amd64 |
| OS Name | ubuntu |
| OS Version | jammy |
| Status | running |
| Runner Status | idle |
| Pool ID | 8ec34c1f-b053-4a5d-80d6-40afdfb389f9 |
| Addresses | 10.198.117.120 |
| Status Updates | 2023-07-08T06:26:46: runner registration token was retrieved |
| | 2023-07-08T06:26:46: using cached runner found in /opt/cache/actions-runner/latest |
| | 2023-07-08T06:26:50: configuring runner |
| | 2023-07-08T06:26:56: runner successfully configured after 1 attempt(s) |
| | 2023-07-08T06:26:56: installing runner service |
| | 2023-07-08T06:26:56: starting service |
| | 2023-07-08T06:26:57: runner successfully installed |
+-----------------+------------------------------------------------------------------------------------+
This URL must be set and must be accessible by the instance. If you wish to restrict access to it, a reverse proxy can be configured to accept requests only from networks in which the runners garm manages will be spun up. This URL doesn't need to be globally accessible, it just needs to be accessible by the instances.
For example, in a scenario where you expose the API endpoint directly, this setting could look like the following:
callback_url = "https://garm.example.com/api/v1/callbacks"Authentication is done using a short-lived JWT token, that gets generated for a particular instance that we are spinning up. That JWT token grants access to the instance to only update it's own status and to fetch metadata for itself. No other API endpoints will work with that JWT token. The validity of the token is equal to the pool bootstrap timeout value (default 20 minutes) plus the garm polling interval (5 minutes).
There is a sample nginx config in the testdata folder. Feel free to customize it whichever way you see fit.
The metadata URL is the base URL for any information an instance may need to fetch in order to finish setting itself up. As this URL may be placed behind a reverse proxy, you'll need to configure it in the garm config file. Ultimately this URL will need to point to the following garm API endpoint:
GET /api/v1/metadataThis URL needs to be accessible only by the instances garm sets up. This URL will not be used by anyone else. To configure it in garm add the following line in the [default] section of your garm config:
metadata_url = "https://garm.example.com/api/v1/metadata"GARM can optionally enable the golang profiling server. This is useful if you suspect garm may be bottlenecking in any way. To enable the profiling server, add the following section to the garm config:
[default]
debug_server = trueAnd restart garm. You can then use the following command to start profiling:
go tool pprof http://127.0.0.1:9997/debug/pprof/profile?seconds=120Important note on profiling when behind a reverse proxy. The above command will hang for a fairly long time. Most reverse proxies will timeout after about 60 seconds. To avoid this, you should only profile on localhost by connecting directly to garm.
It's also advisable to exclude the debug server URLs from your reverse proxy and only make them available locally.
Now that the debug server is enabled, here is a blog post on how to profile golang applications: https://blog.golang.org/profiling-go-programs
By default, GARM logs everything to standard output.
You can optionally log to file by adding the following to your config file:
[default]
# Use this if you'd like to log to a file instead of standard output.
log_file = "/tmp/runner-manager.log"GARM automatically rotates the log if it reaches 500 MB in size or 28 days, whichever comes first.
However, if you want to manually rotate the log file, you can send a SIGHUP signal to the GARM process.
You can add the following to your systemd unit file to enable reload:
[Service]
ExecReload=/bin/kill -HUP $MAINPIDThen you can simply:
systemctl reload garmThis option allows you to stream garm logs directly to your terminal. Set this option to true, then you can use the following command to stream logs:
garm-cli debug-logAn important note on enabling this option when behind a reverse proxy. The log streamer uses websockets to stream logs to you. You will need to configure your reverse proxy to allow websocket connections. If you're using nginx, you will need to add the following to your nginx server config:
location /api/v1/ws {
proxy_pass http://garm_backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
proxy_set_header Host $host;
}