GitHub runner

This machine charm creates self-hosted runners for running GitHub Actions. Each unit of this charm will start a configurable number of OpenStack or LXD based virtual machines to host them. Every runner performs only one job, after which it unregisters from GitHub to ensure that each job runs in a clean environment.

The charm will periodically check the number of runners and spawn or destroy runners as necessary to match the number provided by configuration of runners. Both the reconciliation interval and the number of runners to maintain are configurable.

Like any Juju charm, this charm supports one-line deployment, configuration, integration, scaling, and more. For GitHub runner, this includes:

• Scaling the number of runners up or down
• Configuration for the resources of virtual machines
• Configuration for the reconciliation interval to check/adjust the number of runners
• COS integration

For information about how to deploy, integrate, and manage this charm, see the official GitHub Runner Documentation.

Get started

In order to get familiar with the charm, it is recommended to follow the GitHub Runner tutorial which will guide you through the process of deploying the charm and executing a workflow job using GitHub actions.

For more information about a production deployment, the how-to-guide How to spawn OpenStack runner can be useful.

Basic operations

A usual deployment of the charm can be done with the following command (please replace items in <> with your own values):

juju deploy github-runner --channel=latest/stable --config openstack-clouds-yaml="$(cat clouds.yaml)" --config openstack-flavor=<flavor> --config openstack-network=<openstack-network> --config path=<org>/<repo> --config token=<github-token>

with a cloud configuration (for the OpenStack tenant used to spawn runner VM's) in clouds.yaml:

clouds:
  <cloud-name>:
    auth:
      auth_url: <keystone-auth-url>
      project_name: <project>
      username: <username>
      password: <password>
      user_domain_name: <user-domain-name>
      project_domain_name: <project-domain-name>
    region_name: <region>

Assuming you have already deployed the Github Runner Image Builder charm with the name github-runner-image-builder, you can use the following command to integrate it with the GitHub Runner charm:

juju integrate github-runner-image-builder github-runner

You can scale the amount of virtual machines using

juju config github-runner virtual-machines=5

You can change the reconciliation interval, to e.g. 5 minutes, using

juju config github-runner reconciliation-interval=5

You can trigger reconciliation manually using an action (assuming the unit is named github-runner/0):

juju run github-runner/0 reconcile-runners

If you need to flush and replace the runners with a new set of runners, you can use the following command:

juju run github-runner/0 flush-runners

Integrations

The charm supports multiple integrations, but in order to deploy the charm using OpenStack VM's for the runners, you need it to relate it with an image-builder using the image endpoint. Via this integration, the charm detects the supported images to use for spawning the virtual machines.

Repository structure

This repository contains the charm in the root directory and the Python package github-runner-manager in the github-runner-manager directory. Refer to Contributing for more information.

Learn more

• Read more
• Developer documentation

Project and community

• Issues
• Contributing
• Matrix