diff --git a/README.md b/README.md index 835fd6372..2fdd88003 100644 --- a/README.md +++ b/README.md @@ -15,30 +15,7 @@ runners. Both the reconciliation interval and the number of runners to maintain ## Usage -There are two mandatory configuration options - `path` and `token`. - -* `path` determines the organization or repository that the runner will be registered with; -* `token` is a [GitHub Personal Access Token (PAT)](https://github.com/settings/tokens) (note: this is not the same as the token given in the Add a Runner instructions). The PAT token requires either: - * the **`repo`** ("Full control of private repositories") permission for -use with repositories or; - * both the **`repo`** and **`admin:org`** ("Full control of orgs and teams, read and write org projects") permissions for use with an organization. This is necessary because the charm will create and remove runners as needed to ensure that each runner executes only one job to protect jobs from leaking information to other jobs running on the same runner. - -The number of runners on a single unit is configured using two configuration options that can be both used at the same time: - -* the `containers` option configures the number of LXD container runners; -* the `virtual-machines` option configures the number of LXD virtual machine runners. - -For example, if the charm is deployed with 2 units `juju deploy -n 2` and the `containers` value of 3 is in use, -there will be a total of 6 container based runners, three on each unit. - -## Reconciliation - -Each unit will periodically check the number of runners at the interval specified by `check-interval` to maintain the appropriate number. During the check, all the offline runners are unregistered from GitHub. - -If there are more idle runners than configured, the oldest idle runners are unregistered and destroyed. If there are less idle runners than configured, new runners are spawned and registered with GitHub. - -During each time period, every unit will make one or more API calls to GitHub. The interval may need to be adjusted if the number of units is large enough to trigger [Rate Limiting](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting). - +Please refer to the tutorial in `docs/tutorial/quick-start.md`. ## COS The charm is designed to provide comprehensive metrics and monitoring capabilities for both the Runners and the Charm itself. These metrics are made available through the `cos-agent` integration with the `cos_agent` interface. Additionally, a Grafana Dashboard is included to help visualize these metrics effectively. diff --git a/config.yaml b/config.yaml index 7791c2882..a3036c0f1 100644 --- a/config.yaml +++ b/config.yaml @@ -69,9 +69,9 @@ options: default: "" description: >- Additional comma separated labels to attach to self-hosted runners. By default, the labels - "self-hosted", application name (default: "github-runner"), - architecture (i.e. "x64", "arm64"), os (i.e. "linux"), os-flavor (i.e. "jammy") are set. - Any labels provided via this configuration will be appended to the default values. + "self-hosted", architecture (i.e. "x64", "arm64"), os (i.e. "linux"), os-flavor (i.e. + "jammy") are set. Any labels provided via this configuration will be appended to the default + values. path: type: string default: "" diff --git a/docs/tutorial/quick-start.md b/docs/tutorial/quick-start.md index 8a1b0ddf6..0bc7971f8 100644 --- a/docs/tutorial/quick-start.md +++ b/docs/tutorial/quick-start.md @@ -60,9 +60,7 @@ The charm will spawn new runners on a schedule. During this time, the charm will Once the self-hosted runner is available on GitHub, it can be used to run GitHub Actions jobs similar to runners provided by GitHub. The only difference being the label specified in the `runs-on` of a job. -The self-hosted runner managed by the charm will have the following labels: `self-hosted`, `linux`, and the application name. - -In the above deployment, the application name was not specified, hence the default value of `github-runner` was used. As such, `github-runner` will be a label for the self-hosted runner managed by the application instance. +In addition to the labels added by the GitHub runner application by default, the charm will include labels from the [`labels` charm configuration](https://charmhub.io/github-runner/configurations#labels). To test out the self-hosted runner, create the following file under the path `.github/workflows/runner_test.yaml` in the repository with the following content: @@ -74,7 +72,7 @@ on: jobs: hello-world-test: - runs-on: [self-hosted, github-runner] + runs-on: [self-hosted] steps: - run: echo "hello world" ```