Architecture overview

The GitHub runner deployment utilizes charms to manage the GitHub self-hosted runners. The GARM charm uses the GitHub Actions Runner Manager (GARM) to manage the runners, with the GARM configurator charm providing the configuration for the runners. In addition, the PostgreSQL charm is used to store the state of the GARM.

High-level overview of the deployment

        flowchart TD
  G(["GARM charm"]) --> PG[("PostgreSQL charm")]
  GC(["GARM configurator charm(s)"]) -->|many-to-one| G
  G -->|GitHub API| GH["GitHub"]
  G -->|OpenStack API| OS["OpenStack"]
  OS -->|Spawns multiple| RUN["Runner VMs"]
  RUN -->|callback| G
  COS(["OpenTelemetry Collector charm"]) -->|scrapes metrics| G

Multiple GARM configurator charms can provide configuration to a single GARM charm. Each GARM configurator charm manages the configuration for a single GitHub scaleset.

The diagram above contains the following components:

  • GARM charm: Operates a GitHub Actions Runner Manager (GARM) instance which manages GitHub Scalesets. The Scaleset is a GitHub feature for managing a set of Self-hosted runners.

  • GARM configurator charm: Provides configuration of a single GitHub scaleset to the GARM charm. Multiple GARM configurator charms can be integrated to a single GARM charm.

  • PostgreSQL charm: Provides a PostgreSQL database for the GARM charm to store its state.

  • OpenStack: The substrate where the runner VMs are spawned.

  • OpenTelemetry Collector charm: Scapes the metrics from the GARM charm and sends them to COS.

Ingress

The GARM charm services ingress using the REST API of GARM on the 8080 port. The spawned runners must call back to GARM on this port as part of the runner spawning process.

Observability

The GARM charm exposes Prometheus metrics that can be scraped by a monitoring stack and visualized in Grafana dashboards. The logs of the GARM charm are ingested by Loki to the dashboard.

Security boundaries

The charms control configuration, Juju secret references, relation data, and GARM reconciliation. The deployment environment controls the external ingress, network exposure, PostgreSQL service, OpenStack tenant, GitHub permissions, and observability storage.

The GARM workload serves its API and metrics on port 8080. The workload does not terminate TLS, so external deployments need a TLS-terminating ingress and a restricted network path. GARM metrics are not authenticated by the application and should be reachable only by the monitoring system.

See the security overview for the charm-level security posture and the security how-to guide for operator actions.