GitHub runner operators

This repository contains applications, Juju charms, Grafana dashboards and actions related to operating and using self-hosted GitHub Actions runners.

Repository layout

The Go application code (cmd/, internal/) follows the community Go project layout.

actions/
  enable-log-forwarding/    # GitHub Action: enable log forwarding on runners

charms/
  garm/                     # Juju charm: GARM
  garm-configurator/        # Juju charm: GARM Configurator
  planner-operator/         # Juju charm: GitHub runner planner
    cos_custom/
      grafana_dashboards/   # Grafana dashboards for the planner charm
  tests/                    # Shared charm tests (unit, integration, e2e)
  webhook-gateway-operator/ # Juju charm: GitHub webhook gateway

cmd/
  planner/                  # Application entry point: planner
  waiting-p80-report/       # Application entry point: p80 job waiting time report
  webhook-gateway/          # Application entry point: webhook gateway

internal/                   # Shared Go packages

docs/                       # Documentation

runner_grafana_dashboards/  # Grafana dashboards for runner VM host metrics

scripts/                    # Repository maintenance scripts (e.g. AGENTS.md check)

Charms

This repository contains four charms, representing two different architectures:

The planner architecture, which is no longer in active development, is implemented by the planner-operator and the webhook-gateway-operator charms.

The other architecture is based on GitHub Actions Runner Manager (GARM) and is implemented by the garm and garm-configurator charms.

See Charms in the documentation for their roles and integrations.

Charmhub

Name	Listing
garm	https://charmhub.io/garm
garm-configurator	https://charmhub.io/garm-configurator
github-runner-planner	https://charmhub.io/github-runner-planner
github-runner-webhook-gateway	https://charmhub.io/github-runner-webhook-gateway

Get started

For the current GARM architecture, start with tutorial.

For per-charm roles and integrations, see Charms.

Documentation

Our documentation is stored in the docs directory and can be viewed at https://canonical.com/juju/docs/github-runner-charms/. It is based on the Canonical Sphinx Stack and hosted on Read the Docs. In structuring, the documentation employs the Diátaxis approach.

You may open a pull request with your documentation changes, or you can file a bug to provide constructive feedback or suggestions.

To run the documentation locally before submitting your changes:

cd docs
make run

GitHub runs automatic checks on the documentation to verify spelling, validate links and style guide compliance.

You can (and should) run the same checks locally:

make spelling
make linkcheck
make vale
make lint-md

Project and community

The GitHub runner operators project is a member of the Ubuntu family. It is an open source project that warmly welcomes community projects, contributions, suggestions, fixes, and constructive feedback.

• Code of conduct
• Get support
• Issues
• Matrix
• Contribute

Licensing and trademark

See LICENSE.