A Juju charm for deploying and managing GitHub self-hosted runners on virtual machines.
This charm simplifies the initial deployment and “day N” operations of GitHub self-hosted runners. The charm makes it easy to manage self-hosted runners with security and hardware resource usage in mind.
Operating a self-hosted runner comes with certain security concerns according to GitHub. Just like GitHub’s, the self-hosted runners managed by the charm are isolated in a single-use virtual machine.
Some of the charm dependencies upgrades on a schedule to migrate security risks. The landscape-client charm can be deployed with this charm to ensure other dependencies are up to date.
The charm maintains a set of ephemeral self-hosted runners, each isolated in a single-use virtual machine instance. In addition, resource limits for the self-hosted runners can be configured.
See charm architecture for more information.
The charm also supports observability through the optional cos-agent integration.
Metrics and logs about the runners and the charm itself are collected and sent to the Canonical Observability Stack for analysis and visualisation.
This charm will make operating GitHub self-hosted runners simple and straightforward for DevOps or SRE teams through Juju’s clean interface.
The charm enforces a set of GitHub repository settings as best practice. This is planned to be opt-in in the future. See How to comply with repository policies.
In this documentation
| Tutorials Get started - a hands-on introduction to using the GitHub runner charm for new users |
How-to guides Step-by-step guides covering key operations and common tasks |
| Reference Technical information - specifications, APIs, architecture |
Explanation Concepts - discussion and clarification of key topics |
Contributing to this documentation
Documentation is an important part of this project, and we take the same open-source approach to the documentation as the code. As such, we welcome community contributions, suggestions and constructive feedback on our documentation. Our documentation is hosted on the Charmhub forum to enable easy collaboration. Please use the “Help us improve this documentation” links on each documentation page to either directly change something you see that’s wrong, ask a question, or make a suggestion about a potential change via the comments section.
If there’s a particular area of documentation that you’d like to see that’s missing, please file a bug.
Project and community
The GitHub runner charm is a member of the Ubuntu family. It’s an open-source project that warmly welcomes community projects, contributions, suggestions, fixes, and constructive feedback.
Thinking about using the GitHub runner charm for your next project? Get in touch!
Navigation
| Level | Path | Navlink |
|---|---|---|
| 1 | explanation | Explanation |
| 2 | explanation-arm64 | ARM64 |
| 2 | explanation-charm-architecture | Charm architecture |
| 2 | explanation-ssh-debug | SSH Debug |
| 1 | how-to | How To |
| 2 | how-to-change-path | How to change repository or organization |
| 2 | how-to-change-token | How to change GitHub personal access token |
| 2 | how-to-comply-security | How to comply with security requirements |
| 2 | how-to-configure-denylist | How to restrict self-hosted runner network access |
| 2 | how-to-configure-runner-storage | How to configure runner storage |
| 2 | how-to-contribute | How to contribute |
| 2 | how-to-debug-with-ssh | How to debug with ssh |
| 2 | how-to-deploy-on-arm64 | How to deploy on ARM64 |
| 2 | how-to-integrate-with-cos | How to integrate with COS |
| 2 | how-to-repo-policy | How to comply with repository policies |
| 2 | how-to-run-on-lxd | How to run on LXD cloud |
| 1 | reference | Reference |
| 2 | reference-actions | Actions |
| 2 | reference-arm64 | ARM64 |
| 2 | reference-configurations | Configurations |
| 2 | reference-cos | COS Integration |
| 2 | reference-integrations | Integrations |
| 1 | tutorial | Tutorial |
| 2 | tutorial-managing-resource-usage | Managing resource usage |
| 2 | tutorial-quick-start | Quick start |