{"id":35807030,"url":"https://github.com/canonical/github-runner-operator","last_synced_at":"2026-04-01T18:31:48.221Z","repository":{"id":41872829,"uuid":"355601263","full_name":"canonical/github-runner-operator","owner":"canonical","description":"github-runner-operator - charm repository.","archived":false,"fork":false,"pushed_at":"2026-03-10T21:56:38.000Z","size":53981,"stargazers_count":18,"open_issues_count":13,"forks_count":26,"subscribers_count":7,"default_branch":"main","last_synced_at":"2026-03-10T22:53:32.731Z","etag":null,"topics":["charm","platform-engineering","product-self-hosted-github-runner","squad-apac"],"latest_commit_sha":null,"homepage":"https://charmhub.io/github-runner","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/canonical.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-04-07T15:49:26.000Z","updated_at":"2026-03-10T17:06:13.000Z","dependencies_parsed_at":"2026-03-10T19:01:52.086Z","dependency_job_id":null,"html_url":"https://github.com/canonical/github-runner-operator","commit_stats":null,"previous_names":[],"tags_count":426,"template":false,"template_full_name":null,"purl":"pkg:github/canonical/github-runner-operator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canonical%2Fgithub-runner-operator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canonical%2Fgithub-runner-operator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canonical%2Fgithub-runner-operator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canonical%2Fgithub-runner-operator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/canonical","download_url":"https://codeload.github.com/canonical/github-runner-operator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canonical%2Fgithub-runner-operator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30618835,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-17T08:10:05.930Z","status":"ssl_error","status_checked_at":"2026-03-17T08:10:04.972Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["charm","platform-engineering","product-self-hosted-github-runner","squad-apac"],"created_at":"2026-01-07T13:15:45.873Z","updated_at":"2026-04-01T18:31:48.208Z","avatar_url":"https://github.com/canonical.png","language":"Python","readme":"\u003c!-- vale Canonical.007-Headings-sentence-case = NO --\u003e\n# GitHub runner\n\u003c!-- vale Canonical.007-Headings-sentence-case = YES --\u003e\n\n[![CharmHub Badge](https://charmhub.io/github-runner/badge.svg)](https://charmhub.io/github-runner)\n[![Promote charm](https://github.com/canonical/github-runner-operator/actions/workflows/promote_charm.yaml/badge.svg)](https://github.com/canonical/github-runner-operator/actions/workflows/promote_charm.yaml)\n[![Discourse Status](https://img.shields.io/discourse/status?server=https%3A%2F%2Fdiscourse.charmhub.io\u0026style=flat\u0026label=CharmHub%20Discourse)](https://discourse.charmhub.io)\n\n**Important** Use the [local-lxd](https://charmhub.io/github-runner?channel=local-lxd/stable) track for LXD runners.\n\nThis machine charm creates self-hosted runners for running GitHub Actions. Each unit of this charm will start a configurable number of OpenStack 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.\n\nThe 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.\n\nLike any Juju charm, this charm supports one-line deployment, configuration, integration, scaling, and more. For GitHub runner, this includes:\n* Scaling the number of runners up or down\n* Configuration for the resources of virtual machines\n* Configuration for the reconciliation interval to check/adjust the number of runners\n* [COS integration](https://charmhub.io/topics/canonical-identity-platform/how-to/integrate-cos)\n\nFor information about how to deploy, integrate, and manage this charm, see the official [GitHub Runner Documentation](https://charmhub.io/github-runner).\n\n## Get started\n\nFor information about a production deployment, the how-to-guide\n[How to spawn OpenStack runner](https://charmhub.io/github-runner/docs/how-to-openstack-runner) can be useful.\n\n### Basic operations\nA usual deployment of the charm can be done with the following command (please replace items in `\u003c\u003e` with your own values):\n\n```bash\njuju deploy github-runner --channel=latest/stable --config openstack-clouds-yaml=\"$(cat clouds.yaml)\" --config openstack-flavor=\u003cflavor\u003e --config openstack-network=\u003copenstack-network\u003e --config path=\u003corg\u003e/\u003crepo\u003e --config token=\u003cgithub-token\u003e\n```\n\nwith a cloud configuration (for the OpenStack tenant used to spawn runner VMs) in `clouds.yaml`:\n\n```yaml\nclouds:\n  \u003ccloud-name\u003e:\n    auth:\n      auth_url: \u003ckeystone-auth-url\u003e\n      project_name: \u003cproject\u003e\n      username: \u003cusername\u003e\n      password: \u003cpassword\u003e\n      user_domain_name: \u003cuser-domain-name\u003e\n      project_domain_name: \u003cproject-domain-name\u003e\n    region_name: \u003cregion\u003e\n  ```\n\nAssuming you have already deployed the [GitHub Runner Image Builder](https://charmhub.io/github-runner-image-builder) charm\nwith the name `github-runner-image-builder`, you can use the following command to integrate it with the GitHub Runner charm:\n\n```bash\njuju integrate github-runner-image-builder github-runner\n```\n\nYou can scale the amount of virtual machines using\n\n```bash\njuju config github-runner base-virtual-machines=5\n```\n\nYou can change the reconciliation interval, to e.g. five minutes, using\n\n```bash\njuju config github-runner reconciliation-interval=5\n```\n\nYou can trigger reconciliation manually using an action (assuming the unit is named `github-runner/0`):\n\n```bash\njuju run github-runner/0 reconcile-runners\n```\n\nIf you need to flush and replace the runners with a new set of runners, you can use the following command:\n\n```bash\njuju run github-runner/0 flush-runners\n```\n\n## Overview of the GitHub runner ecosystem\n\nThe `github-runner` charm integrates with several other charms that work\ntogether to facilitate the deployment, management and debugging of\nself-hosted GitHub runners. Below is a high-level overview of the key\ncharms and their interactions:\n\n* [GitHub Runner](https://charmhub.io/github-runner): The central component that manages self-hosted GitHub runners. It interacts with OpenStack to spawn runner VMs and communicates with GitHub to register and manage runners.\n* [Image Builder](https://charmhub.io/github-runner-image-builder): Responsible for generating images. It builds images on the builder OpenStack project and uploads them to the GitHub Runner OpenStack project.\n* [MongoDB](https://charmhub.io/mongodb): Acts as a message queue to handle reactive runner requests. The [github-runner-webhook-router](https://charmhub.io/github-runner-webhook-router) charm will put events in MongoDB that will be consumed by the `github-runner` charm. Only for reactive runners.\n* [tmate-ssh-server](https://charmhub.io/tmate-ssh-server): Provides terminal-sharing capabilities to enable debugging of GitHub runners. Optional.\n* [COS lite stack](https://charmhub.io/topics/canonical-observability-stack/editions/lite): Provides observability to the GitHub runners ecosystem. Optional.\n\nBelow is a diagram representing these components and their relationships, excluding the [COS lite stack](https://charmhub.io/topics/canonical-observability-stack/editions/lite):\n\n```mermaid\nC4Container\ntitle Container diagram for the github-runner Charm System\n Container_Boundary(c1, \"Image Builder\") {\n    Container(imagebuilder, \"Image Builder\", \"\", \"Provides images to all related charms\")\n }\n    System_Ext(osbuilding, \"OpenStack\", \"OpenStack deployment used for building images\")\nContainer_Boundary(c2, \"GitHub Runner\"){\n    Container(githubrunner, \"GitHub Runner Charm\", \"\", \"Manages self-hosted runners\")\n}\nContainer_Boundary(c3, \"monbodb\"){\n    Container(mongodb, \"MongoDB\", \"\", \"Used as a message queue for reactive runner requests\")\n}\nContainer_Boundary(c4, \"tmate-ssh-server\"){\n    Container(tmate_ssh, \"tmate-ssh-server\", \"\", \"Terminal sharing capabilities to debug GitHub runners\")\n}\n\nContainer_Boundary(c5, \"github-runner-webhook-router\"){\n    Container(router, \"github-runner-webhook-router\", \"\", \"Listens to GitHub webhooks\")\n}\n\n    Rel(imagebuilder, osbuilding, \"builds images\")\n    UpdateRelStyle(imagebuilder, osbuilding, $offsetY=\"-30\", $offsetX=\"10\")\n    Rel(imagebuilder, osgithubrunner, \"uploads images\")\n    UpdateRelStyle(imagebuilder, osgithubrunner, $offsetY=\"-30\", $offsetX=\"-90\")\n    Rel(imagebuilder, githubrunner, \"image ids\")\n    UpdateRelStyle(imagebuilder, githubrunner, $offsetY=\"-10\", $offsetX=\"-30\")\n    System_Ext(osgithubrunner, \"OpenStack\", \"OpenStack deployment used for spawning runner VMs\")\n    System_Ext(github, \"GitHub\", \"GitHub API\")\n    Rel(githubrunner, osgithubrunner, \"spawns VMs\")\n    UpdateRelStyle(githubrunner, osgithubrunner, $offsetY=\"-30\", $offsetX=\"10\")\n    Rel(githubrunner, github, \"Manage runners\")\n    Rel(githubrunner, imagebuilder, \"OpenStack credentials\")\n    UpdateRelStyle(githubrunner, imagebuilder, $offsetY=\"10\", $offsetX=\"-60\")\n    Rel(mongodb, githubrunner, \"database credentials\")\n    Rel(tmate_ssh, githubrunner, \"debug-ssh credentials\")\n    Rel(router, mongodb, \"new runner requests\")\n```\n\n\n## Integrations\nThe charm supports [multiple integrations](https://charmhub.io/github-runner/integrations),\nbut in order to deploy the charm using OpenStack VMs for the runners, you need it to relate it\nwith an image-builder using the [image](https://charmhub.io/github-runner/integrations#image) \nendpoint. Through this integration, the charm detects the supported images to use for spawning the virtual machines.\n\n\n## Repository structure\n\nThis repository contains the charm in the root directory and the Python package `github-runner-manager` in the\n`github-runner-manager` directory. Refer to [Contributing](CONTRIBUTING.md) for more information.\n\n\n## Learn more\n* [Read more](https://charmhub.io/github-runner)\n* [Developer documentation](https://charmhub.io/github-runner/docs/how-to-contribute)\n\n## Project and community\n* [Issues](https://github.com/canonical/github-runner-operator/issues)\n* [Contributing](https://charmhub.io/github-runner/docs/how-to-contribute)\n* [Matrix](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcanonical%2Fgithub-runner-operator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcanonical%2Fgithub-runner-operator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcanonical%2Fgithub-runner-operator/lists"}