Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix the docs in the quick docs on the label #374

Merged
merged 7 commits into from
Sep 20, 2024
Merged
Show file tree
Hide file tree
Changes from 5 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 1 addition & 24 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <charm> -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 quick start guide in `docs/tutorial/quick-start.md`.
erinecon marked this conversation as resolved.
Show resolved Hide resolved

## 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.
Expand Down
6 changes: 3 additions & 3 deletions config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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: ""
Expand Down
6 changes: 2 additions & 4 deletions docs/tutorial/quick-start.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -74,7 +72,7 @@ on:

jobs:
hello-world-test:
runs-on: [self-hosted, github-runner]
runs-on: [self-hosted]
steps:
- run: echo "hello world"
```
Expand Down
Loading