From e225a87b9b270585db593be1fda488ab24b250d2 Mon Sep 17 00:00:00 2001 From: Yanks Yoon <37652070+yanksyoon@users.noreply.github.com> Date: Fri, 13 Sep 2024 19:30:38 +0800 Subject: [PATCH 1/3] test: run test w/ new lib (#373) * test: run test w/ new lib * chore: replace merged hash --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 6be16381d..d49ee5719 100644 --- a/requirements.txt +++ b/requirements.txt @@ -14,4 +14,4 @@ PyYAML ==6.0.* pyOpenSSL==24.2.1 kombu==5.4.1 pymongo==4.8.0 -github_runner_manager @ git+https://github.com/canonical/github-runner-manager.git@771530633cd8b3cb18cb95399c234c82118b77e2 +github_runner_manager @ git+https://github.com/canonical/github-runner-manager.git@6ee40e296f92f191dd12b1e24a613dfdbdc70f99 From ce408e1db20350d6c565350eed111f9917e2235c Mon Sep 17 00:00:00 2001 From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com> Date: Tue, 17 Sep 2024 12:53:08 +0200 Subject: [PATCH 2/3] chore(deps): update dependency pydantic to v1.10.18 (#353) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: arturo-seijas <102022572+arturo-seijas@users.noreply.github.com> --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index d49ee5719..48fc691a8 100644 --- a/requirements.txt +++ b/requirements.txt @@ -7,7 +7,7 @@ pylxd @ git+https://github.com/canonical/pylxd requests typing-extensions cryptography <=43.0.1 -pydantic ==1.10.17 +pydantic ==1.10.18 cosl ==0.0.15 # juju 3.1.2.0 depends on pyyaml<=6.0 and >=5.1.2 PyYAML ==6.0.* From e3858e3f56c9a161c454db609ffce92b7684e8fb Mon Sep 17 00:00:00 2001 From: Erin Conley Date: Tue, 17 Sep 2024 14:03:15 -0400 Subject: [PATCH 3/3] Update docs (#376) * Update links in index.md * Update quick-start.md Reformat a note Capitalise Juju where appropriate Add a semicolon * Capitalise Juju in managing-resource-usage.md * Replace comma with semicolon in add-custom-labels.md * Update language change-path.md Change "organization" to British spelling * Update reference link in change-token.md * Update comply-security.md Reformat link in the first sentence Link repo-policy-compliance README Format workplace_dispatch, push, and schedule as code Rewording * Update configure-runner-storage.md Capitalise Juju where appropriate Add "the" in the first sentence * Prerequisites --> Requirements * Update deploy-on-arm64.md Prerequisites --> Requirements Update the header levels * Update integrate-with-cos.md Prerequisites --> Requirements Update header levels Capitalisation Update broken link Reformat a note * Update openstack-runner.md Capitalisation Update spelling to British English Add commas * Update run-on-lxd.md Capitalise Juju Reformat a note * Capitalise Juju in arm64.md * Update list in external-access.md Change last item to match the others in the list * Update arm64.md Update to British English Add "be" * Update charm-architecture.md Capitalise Juju where appropriate Update last item in "GitHub API usage" list to be consistent with the other items * Setup --> set up * change a note to a warning --- docs/explanation/arm64.md | 6 +++--- docs/explanation/charm-architecture.md | 8 ++++---- docs/explanation/ssh-debug.md | 2 +- docs/how-to/add-custom-labels.md | 2 +- docs/how-to/change-path.md | 8 ++++---- docs/how-to/change-token.md | 2 +- docs/how-to/comply-security.md | 8 ++++---- docs/how-to/configure-runner-storage.md | 14 +++++++------- docs/how-to/debug-with-ssh.md | 2 +- docs/how-to/deploy-on-arm64.md | 8 ++++---- docs/how-to/integrate-with-cos.md | 10 +++++----- docs/how-to/openstack-runner.md | 16 ++++++++-------- docs/how-to/run-on-lxd.md | 8 +++----- docs/index.md | 8 ++++---- docs/reference/arm64.md | 4 ++-- docs/reference/external-access.md | 4 ++-- docs/tutorial/managing-resource-usage.md | 6 +++--- docs/tutorial/quick-start.md | 10 +++++----- 18 files changed, 62 insertions(+), 64 deletions(-) diff --git a/docs/explanation/arm64.md b/docs/explanation/arm64.md index 30e508474..b80f81335 100644 --- a/docs/explanation/arm64.md +++ b/docs/explanation/arm64.md @@ -6,8 +6,8 @@ GitHub runner uses [LXD](https://github.com/canonical/lxd) to create a virtual m GitHub runner's binary. Some versions of the ARM64 architecture do not support nested virtualizations. -Furthermore LXD by default uses QEMU with KVM acceleration options and such behavior cannot -overridden. When run on a machine without KVM support, +Furthermore LXD by default uses QEMU with KVM acceleration options and such behaviour cannot +be overridden. When run on a machine without KVM support, the following error will occur: ``` Error: Failed instance creation: Failed creating instance record: Instance type "virtual-machine" @@ -22,4 +22,4 @@ to be further developed. - Kernel (KVM): upstream not yet ready - Userspace programs (e.g. qemu): unsupported. -Therefore, it is currently necessary that the charm is deployed on a bare metal instance. \ No newline at end of file +Therefore, it is currently necessary that the charm is deployed on a bare metal instance. diff --git a/docs/explanation/charm-architecture.md b/docs/explanation/charm-architecture.md index 6f60613ff..5bf4cf9aa 100644 --- a/docs/explanation/charm-architecture.md +++ b/docs/explanation/charm-architecture.md @@ -21,8 +21,8 @@ On schedule or upon configuration change, the charm performs a reconcile to ensu To prevent disk IO exhaustion on the Juju machine on disk-intensive GitHub workflows, the charm has two storage options provided by [`runner-storage` configuration](https://charmhub.io/github-runner/configure#runner-storage): -- Use memory of the juju machine as disk. Under this option, the [`vm-disk` configuration](https://charmhub.io/github-runner/configure#vm-disk) can impact the memory usage of the Juju machine. -- Use storage mount by juju as the disk. +- Use memory of the Juju machine as disk. Under this option, the [`vm-disk` configuration](https://charmhub.io/github-runner/configure#vm-disk) can impact the memory usage of the Juju machine. +- Use storage mount by Juju as the disk. ## Virtual machine image @@ -84,7 +84,7 @@ The charm requires a GitHub personal access token for the [`token` configuration - Requesting self-hosted runner removal tokens - Requesting a list of runner applications - Requesting a list of self-hosted runners configured in an organization or repository -- Deletion of self-hosted runners +- Deleting self-hosted runners The token is also passed to [repo-policy-compliance](https://github.com/canonical/repo-policy-compliance) to access GitHub API for the service. @@ -129,4 +129,4 @@ into the file `/var/log/github-runner-metrics.log`. For comprehensive details, p pertinent [specification](https://discourse.charmhub.io/t/specification-isd075-github-runner-cos-integration/12084). Subsequently, the `grafana-agent` transmits this log file to Loki, facilitating access for Grafana's visualisation capabilities. -Notably, most events are transmitted during reconciliation. This approach prioritises long-term monitoring over real-time updates, aligning with the intended monitoring objectives. \ No newline at end of file +Notably, most events are transmitted during reconciliation. This approach prioritises long-term monitoring over real-time updates, aligning with the intended monitoring objectives. diff --git a/docs/explanation/ssh-debug.md b/docs/explanation/ssh-debug.md index 84a525455..617ea5d71 100644 --- a/docs/explanation/ssh-debug.md +++ b/docs/explanation/ssh-debug.md @@ -15,4 +15,4 @@ of tmate session with `-a` option, which adds the user's SSH key to `~/.ssh/auth By default, if there are any overlapping IPs within the `denylist` config option with the IP assigned to `tmate-ssh-server`, an exception to that IP will be made so that the `debug-ssh` -relation can be setup correctly. +relation can be set up correctly. diff --git a/docs/how-to/add-custom-labels.md b/docs/how-to/add-custom-labels.md index f01d549f5..fd51565fe 100644 --- a/docs/how-to/add-custom-labels.md +++ b/docs/how-to/add-custom-labels.md @@ -11,5 +11,5 @@ juju config labels= ``` An example of a COMMA_SEPARATED_LABELS value would be "large,gpu", "small,arm64". -Accepted values are alphanumeric values with underscores (_), whitespaces before and after the the +Accepted values are alphanumeric values with underscores (_); whitespaces before and after the the word will be automatically trimmed. diff --git a/docs/how-to/change-path.md b/docs/how-to/change-path.md index 7a925fa85..ef221407f 100644 --- a/docs/how-to/change-path.md +++ b/docs/how-to/change-path.md @@ -1,9 +1,9 @@ -# How to change repository or organization +# How to change repository or organisation -This charm supports changing the GitHub repository or GitHub organization the self-hosted runners are connected to. +This charm supports changing the GitHub repository or GitHub organisation the self-hosted runners are connected to. -By using [`juju config`](https://juju.is/docs/juju/juju-config) to change the [charm configuration path](https://charmhub.io/github-runner/configure#path) to another repository or organization, the charm unregisters and removes the old self-hosted runners and instantiates new ones for the new configuration. +By using [`juju config`](https://juju.is/docs/juju/juju-config) to change the [charm configuration path](https://charmhub.io/github-runner/configure#path) to another repository or organisation, the charm unregisters and removes the old self-hosted runners and instantiates new ones for the new configuration. ```shell juju config path= -``` \ No newline at end of file +``` diff --git a/docs/how-to/change-token.md b/docs/how-to/change-token.md index 77de846c2..c058840bc 100644 --- a/docs/how-to/change-token.md +++ b/docs/how-to/change-token.md @@ -10,7 +10,7 @@ An example classic token scope for repository use: - `repo` -For managing token scopes (fine-grained token), refer to (reference/token-scopes.md). +For managing token scopes (fine-grained token), refer to [the token scopes Reference page](https://charmhub.io/github-runner/docs/reference-token-scopes). By using [`juju config`](https://juju.is/docs/juju/juju-config) to change the [charm configuration token](https://charmhub.io/github-runner/configure#token) the charm unregisters and removes the old self-hosted runners and instantiates new ones. diff --git a/docs/how-to/comply-security.md b/docs/how-to/comply-security.md index e7586e96c..9368115d7 100644 --- a/docs/how-to/comply-security.md +++ b/docs/how-to/comply-security.md @@ -1,8 +1,8 @@ # How to comply with security requirements -[Running code inside the GitHub self-hosted runner poses significant security risk of arbitrary code execution according to GitHub](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-security). The self-hosted runners managed by the charm are isolated in its own single-use virtual machine instance. In addition, the charm enforces some repository settings to ensure all code running on the self-hosted runners is reviewed by someone trusted. +According to GitHub, running code inside the GitHub self-hosted runner [poses a significant security risk of arbitrary code execution](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-security). The self-hosted runners managed by the charm are isolated in its own single-use virtual machine instance. In addition, the charm enforces some repository settings to ensure all code running on the self-hosted runners is reviewed by someone trusted. -The repository settings are enforced with this [Python library](https://github.com/canonical/repo-policy-compliance). The rules enforced are different depending on how the GitHub Actions workflow is triggered. The details can be found in the README. +The repository settings are enforced with the [repo-policy-compliance Python library](https://github.com/canonical/repo-policy-compliance). The enforced rules differ depending on how the GitHub Actions workflow is triggered. The details can be found in the [README](https://github.com/canonical/repo-policy-compliance/blob/main/README.md). In this guide, a recommended set of policies will be presented, but any set repository settings that passes the [Python library](https://github.com/canonical/repo-policy-compliance) checks will work with the self-hosted runners managed by this charm. @@ -16,8 +16,8 @@ In this guide, a recommended set of policies will be presented, but any set repo - `Required signed commits` - `Do not allow bypassing the above settings` -With these settings, the common workflow of creating branches with pull requests and merging to the default branch is supported. Other GitHub Actions workflow triggers such as workflow_dispatch, push, and schedule are supported as well. +With these settings, the common workflow of creating branches with pull requests and merging to the default branch is supported. Other GitHub Actions workflow triggers such as `workflow_dispatch`, `push`, and `schedule` are supported as well. ### Working with outside collaborators -Generally, outside collaborators are not completely trusted, but still would need to contribute in some manner. As such, this charm requires pull requests by outside collaborators to be reviewed by someone with `write` permission or above. Once the review is completed, the reviewer should add a comment including the following string: `/canonical/self-hosted-runners/run-workflows `, where `` is the commit SHA of the approved commit. Once posted, the self-hosted runners will run the workflow for this commit. \ No newline at end of file +Generally, outside collaborators are not completely trusted, but still would need to contribute in some manner. As such, this charm requires pull requests by outside collaborators to be reviewed by someone with `write` permission or above. Once the review is completed, the reviewer should add a comment including the following string: `/canonical/self-hosted-runners/run-workflows `, where `` is the commit SHA of the approved commit. Once posted, the self-hosted runners will run the workflow for this commit. diff --git a/docs/how-to/configure-runner-storage.md b/docs/how-to/configure-runner-storage.md index 68333c16d..e659c6648 100644 --- a/docs/how-to/configure-runner-storage.md +++ b/docs/how-to/configure-runner-storage.md @@ -1,17 +1,17 @@ # How to configure runner storage -To prevent GitHub Action job from exhausting the disk IO of the juju machine hosting the charm, the charm provides two storage options to be configured as the LXD instance root disk: +To prevent the GitHub Action job from exhausting the disk IO of the Juju machine hosting the charm, the charm provides two storage options to be configured as the LXD instance root disk: - Random access memory as disk -- Storage provided by juju +- Storage provided by Juju This is configured with the [`runner-storage`](https://charmhub.io/github-runner/configure#runner-storage) option. The configuration should be set during deployment and cannot be changed. ## Random access memory as disk -The random access memory of the juju machine is configured as LXD storage and used as the root disk for the LXD instances. +The random access memory of the Juju machine is configured as LXD storage and used as the root disk for the LXD instances. -The `runner-storage` configuration needs to be set to `memory` during deployment, and the juju machine constraints should have enough memory for the virtual machine memory and disk. See [Managing resource usage](https://charmhub.io/github-runner/docs/managing-resource-usage). +The `runner-storage` configuration needs to be set to `memory` during deployment, and the Juju machine constraints should have enough memory for the virtual machine memory and disk. See [Managing resource usage](https://charmhub.io/github-runner/docs/managing-resource-usage). An example deployment: @@ -19,9 +19,9 @@ An example deployment: juju deploy github-runner --constraints="cores=4 mem=16G root-disk=20G virt-type=virtual-machine" --config token= --config path= --config runner-storage=memory --config vm-memory=2GiB --config vm-disk=10GiB ``` -## Storage provided by juju +## Storage provided by Juju -The juju storage needs to be mounted during deployment, and the `runner-storage` configuration should be set to `juju-storage` during deployment. +The Juju storage needs to be mounted during deployment, and the `runner-storage` configuration should be set to `juju-storage` during deployment. An example deployment: @@ -29,4 +29,4 @@ An example deployment: juju deploy github-runner --constraints="cores=4 mem=6G root-disk=30G virt-type=virtual-machine" --config token= --config path= --config runner-storage=juju-storage --config vm-memory=2GiB --config vm-memory=10GiB --storage runner=rootfs ``` -The above example uses `rootfs`, which is using the root disk of the juju machine. Hence the root-disk size was increase to 30G. +The above example uses `rootfs`, which is using the root disk of the Juju machine. Hence the root-disk size was increase to 30G. diff --git a/docs/how-to/debug-with-ssh.md b/docs/how-to/debug-with-ssh.md index e0dabb4df..18453123c 100644 --- a/docs/how-to/debug-with-ssh.md +++ b/docs/how-to/debug-with-ssh.md @@ -5,7 +5,7 @@ The charm exposes an integration `debug-ssh` interface which can be used with environment variables to be picked up by [action-tmate](https://github.com/canonical/action-tmate/) for automatic configuration. -## Prerequisites +## Requirements To enhance the security of self-hosted runners and its infrastructure, only authorized connections can be established. Hence, action-tmate users must have diff --git a/docs/how-to/deploy-on-arm64.md b/docs/how-to/deploy-on-arm64.md index 9d8fbd7cb..a08456354 100644 --- a/docs/how-to/deploy-on-arm64.md +++ b/docs/how-to/deploy-on-arm64.md @@ -7,13 +7,13 @@ deployment currently only supports ARM64 bare-metal machines due to the limitati The following uses AWS's [m7g.metal](https://aws.amazon.com/blogs/aws/now-available-bare-metal-arm-based-ec2-instances/) instance to deploy the GitHub Runner on ARM64 architecture. -### Prerequisites +## Requirements 1. Juju with ARM64 bare metal instance availability. - On AWS: `juju bootstrap aws ` 2. GitHub [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) 3. Repository to register the GitHub runners. -### Deployment steps +## Deployment steps Run the following command: ```shell @@ -26,5 +26,5 @@ The units may take several minutes to settle. Furthermore, due to charm restart the Unit may become lost for a few minutes. This is an expected behavior and the unit should automatically re-register itself onto the Juju controller after a successful reboot. -Goto the repository > Settings (tab) > Actions (left menu dropdown) > Runners and verify that the -runner has successfully registered and is online. \ No newline at end of file +Go to the repository > Settings (tab) > Actions (left menu dropdown) > Runners and verify that the +runner has successfully registered and is online. diff --git a/docs/how-to/integrate-with-cos.md b/docs/how-to/integrate-with-cos.md index fd685b5fb..e7cf26841 100644 --- a/docs/how-to/integrate-with-cos.md +++ b/docs/how-to/integrate-with-cos.md @@ -4,17 +4,17 @@ This guide demonstrates the process of integrating with the [Canonical Observabi The `cos-agent` integration can be consumed by the [grafana-agent](https://charmhub.io/grafana-agent) charm, which is responsible for transmitting logs, Prometheus metrics, and Grafana dashboards to the COS stack. -**Note:** The Github Runner charm and grafana-agent charm function as machine charms, while the COS stack comprises Kubernetes charms. Therefore, establishing [cross-model integrations](https://juju.is/docs/juju/manage-cross-model-integrations) is necessary, along with potential firewall rule configurations to allow inter-model traffic. +> NOTE: The Github Runner charm and `grafana-agent` charm function as machine charms, while the COS stack comprises Kubernetes charms. Therefore, establishing [cross-model integrations](https://juju.is/docs/juju/manage-cross-model-integrations) is necessary, along with potential firewall rule configurations to allow inter-model traffic. -### Prerequisites +## Requirements 1. Deploy the Github Runner Charm with the application name `github-runner` in the `machine-model`. 2. Deploy the COS stack on a Kubernetes cloud (refer to [this tutorial](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)). - Ensure `loki`, `prometheus`, `grafana`, and `traefik` charms are deployed within a model named `k8s-model`. - - Integration between `loki` and `traefik` is required to enable `grafana-agent` to transmit logs by setting a public IP for the loki service accessible from the machine cloud. + - Integration between `loki` and `traefik` is required to enable `grafana-agent` to transmit logs by setting a public IP for the Loki service accessible from the machine cloud. - Confirm that both models exist in the same Juju controller. If not, adjust the model names by appending the respective controller name (followed by ":") in the subsequent steps. Ensure you have the necessary [permissions](https://juju.is/docs/juju/manage-cross-model-integrations#heading--control-access-to-an-offer) to consume the offers. -### Steps +## Steps 1. Deploy the `grafana-agent` charm in the machine model. ```shell @@ -47,4 +47,4 @@ The `cos-agent` integration can be consumed by the [grafana-agent](https://charm ``` You should now be able to access a Grafana Dashboard named `GitHub Self-Hosted Runner Metrics`, displaying metrics, and another named `System Resources` exhibiting host resources in Grafana. -Additionally, you can explore Loki logs using Grafana's Explore function. For detailed information about the specific metrics in the `GitHub Self-Hosted Runner Metrics` dashboard, refer to [Metrics](https://charmhub.io/github-runner/docs/cos). \ No newline at end of file +Additionally, you can explore Loki logs using Grafana's Explore function. For detailed information about the specific metrics in the `GitHub Self-Hosted Runner Metrics` dashboard, refer to [Metrics](https://charmhub.io/github-runner/docs/reference-cos). diff --git a/docs/how-to/openstack-runner.md b/docs/how-to/openstack-runner.md index 6e3f2ba61..3a512268d 100644 --- a/docs/how-to/openstack-runner.md +++ b/docs/how-to/openstack-runner.md @@ -1,8 +1,8 @@ # How to spawn OpenStack runner The charm can be configured to use OpenStack cloud for creating runners. -The charm must be deployed with the correct configuration and once the OpenStack integration is -enabled the charm cannot be changed to use other virtualization methods. +The charm must be deployed with the correct configuration, and once the OpenStack integration is +enabled, the charm cannot be changed to use other virtualization methods. ## Configuration @@ -24,7 +24,7 @@ The image will take about 10-15 minutes to build and be ready via the relation. ### OpenStack clouds.yaml -The `openstack-clouds-yaml` configuration contains the authorization information needed for the charm to log in to the openstack cloud. +The `openstack-clouds-yaml` configuration contains the authorization information needed for the charm to log in to the OpenStack cloud. The first cloud in the `clouds.yaml` is used by the charm. Here is a sample of the `clouds.yaml`: @@ -44,16 +44,16 @@ clouds: The `clouds.yaml` documentation is [here](https://docs.openstack.org/python-openstackclient/pike/configuration/index.html#clouds-yaml). -### OpenStack Flavor +### OpenStack Flavour -The `openstack-flavor` configuration sets the flavor used to create the OpenStack virtual machine when spawning new runners. -The flavor is tied with the vCPU, memory, and storage. -The flavors documentation is [here](https://docs.openstack.org/nova/rocky/user/flavors.html). +The `openstack-flavor` configuration sets the flavour used to create the OpenStack virtual machine when spawning new runners. +The flavour is tied with the vCPU, memory, and storage. +The flavours documentation is [here](https://docs.openstack.org/nova/rocky/user/flavors.html). ### OpenStack Network The `openstack-network` configuration sets the network used to create the OpenStack virtual machine when spawning new runners. -Note that the network should be configured to allow traffic from the charm deployment (juju machine) to the OpenStack virtual machine, and traffic from the OpenStack virtual machine to GitHub. +Note that the network should be configured to allow traffic from the charm deployment (Juju machine) to the OpenStack virtual machine, and traffic from the OpenStack virtual machine to GitHub. The network documentation is [here](https://docs.openstack.org/neutron/latest/admin/intro-os-networking.html). diff --git a/docs/how-to/run-on-lxd.md b/docs/how-to/run-on-lxd.md index 948ce9871..0ddec7a97 100644 --- a/docs/how-to/run-on-lxd.md +++ b/docs/how-to/run-on-lxd.md @@ -2,7 +2,7 @@ This machine charm needs to run on virtual machines with nested virtualization enabled. -By default, juju machines on LXD are containers. +By default, Juju machines on LXD are containers. To run this charm on LXD, add `virt-type=virtual-machine` to the constraints during deployment: @@ -11,11 +11,9 @@ juju deploy github-runner --constraints="cores=2 mem=16G virt-type=virtual-machi --config token= --config path= ``` -This constraint ensures the juju machine hosting the charm is a LXD virtual machine. See +This constraint ensures the Juju machine hosting the charm is a LXD virtual machine. See [Managing resource usage](https://charmhub.io/github-runner/docs/managing-resource-usage) for recommendation on `cores` and `mem` constraint. -### Notes - -The name of the application must not be longer than 29 characters. This is due to the nature of LXD +> NOTE: The name of the application must not be longer than 29 characters. This is due to the nature of LXD pathing that must not exceed 108 bytes. 79 characters are reserved for path naming convention. diff --git a/docs/index.md b/docs/index.md index 1feb8c081..e39a4fe1d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,7 +9,7 @@ Some of the charm dependencies upgrades on a schedule to migrate security risks. 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](https://charmhub.io/github-runner/docs/charm-architecture) for more information. +See [charm architecture](https://charmhub.io/github-runner/docs/explanation-charm-architecture) for more information. The charm operates in a stateless manner. It can be redeployed without losing any data and there is no need to backup the charm's state. @@ -18,7 +18,7 @@ Metrics and logs about the runners and the charm itself are collected and sent t 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](https://charmhub.io/github-runner/docs/repo-policy). +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](https://charmhub.io/github-runner/docs/how-to-repo-policy). ## In this documentation @@ -42,7 +42,7 @@ The GitHub runner charm is a member of the Ubuntu family. It's an open-source pr - [Join our online chat](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) - [Contribute](Contribute) -Thinking about using the GitHub runner charm for your next project? [Get in touch](https://chat.charmhub.io/charmhub/channels/charm-dev)! +Thinking about using the GitHub runner charm for your next project? [Get in touch](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)! # Contents @@ -70,4 +70,4 @@ Thinking about using the GitHub runner charm for your next project? [Get in touc 1. [Token scopes](reference/token-scopes.md) 1. [Tutorial](tutorial) 1. [Managing resource usage](tutorial/managing-resource-usage.md) - 1. [Quick start](tutorial/quick-start.md) \ No newline at end of file + 1. [Quick start](tutorial/quick-start.md) diff --git a/docs/reference/arm64.md b/docs/reference/arm64.md index cc928f62d..d1bd9b7b8 100644 --- a/docs/reference/arm64.md +++ b/docs/reference/arm64.md @@ -2,5 +2,5 @@ ### AWS bare metal instances -Use any of the [ARM64 metal instances](https://aws.amazon.com/ec2/instance-types/) to provide juju -with ARM64 bare metal instances. Some of the examples include: a1.metal, m7g.metal. \ No newline at end of file +Use any of the [ARM64 metal instances](https://aws.amazon.com/ec2/instance-types/) to provide Juju +with ARM64 bare metal instances. Some of the examples include: a1.metal, m7g.metal. diff --git a/docs/reference/external-access.md b/docs/reference/external-access.md index d12a4e22f..98a197bb1 100644 --- a/docs/reference/external-access.md +++ b/docs/reference/external-access.md @@ -7,10 +7,10 @@ The GitHub Runner Charm itself requires access to the - Ubuntu package repositories (e.g. to install packages) - Snap store (e.g. to install LXD or aproxy) - [Ubuntu Cloud Images](https://cloud-images.ubuntu.com/) (for the image used by a runner) -- npm registry to download and install specific packages +- npm registry (e.g. to download and install specific packages) In addition, access is required depending on the requirements of the workloads that the runners will be running (as they will be running on the same machine as the charm). More details on network configuration can be found in the -[charm architecture documentation](https://charmhub.io/github-runner/docs/charm-architecture). \ No newline at end of file +[charm architecture documentation](https://charmhub.io/github-runner/docs/charm-architecture). diff --git a/docs/tutorial/managing-resource-usage.md b/docs/tutorial/managing-resource-usage.md index 73da46d3c..ddac4fb13 100644 --- a/docs/tutorial/managing-resource-usage.md +++ b/docs/tutorial/managing-resource-usage.md @@ -12,9 +12,9 @@ The minimum requirements for a single virtual machine are: ## Juju machine resource usage -It is recommended the juju machine has a minimum of 4GiB of memory dedicated to itself. Generally, 20GiB of disk is provisioned for the juju machine for the Juju logs. +It is recommended the Juju machine has a minimum of 4GiB of memory dedicated to itself. Generally, 20GiB of disk is provisioned for the Juju machine for the Juju logs. -The juju machine will also need the enough resources to host the virtual machines. +The Juju machine will also need the enough resources to host the virtual machines. The recommended combined resource usage is: @@ -28,4 +28,4 @@ If memory is used as [runner storage](https://charmhub.io/github-runner/docs/con ## Juju machine constraints -During [deployment of the charm](https://juju.is/docs/juju/juju-deploy), constraints can be used to specify the juju machine resource requirements. For example, `juju deploy github-runner --constraints="cores=4 mem=16G disk=20G"`. \ No newline at end of file +During [deployment of the charm](https://juju.is/docs/juju/juju-deploy), constraints can be used to specify the Juju machine resource requirements. For example, `juju deploy github-runner --constraints="cores=4 mem=16G disk=20G"`. diff --git a/docs/tutorial/quick-start.md b/docs/tutorial/quick-start.md index f7b3b0cdd..8a1b0ddf6 100644 --- a/docs/tutorial/quick-start.md +++ b/docs/tutorial/quick-start.md @@ -12,7 +12,7 @@ - GitHub Account. - Juju 3 installed. -- Juju controller on OpenStack or LXD (see [How to run on LXD cloud](https://charmhub.io/github-runner/docs/how-to-run-on-lxd)) and a juju model. +- Juju controller on OpenStack or LXD (see [How to run on LXD cloud](https://charmhub.io/github-runner/docs/how-to-run-on-lxd)) and a Juju model. For more information about how to install and use Juju, see [Get started with Juju](https://juju.is/docs/olm/get-started-with-juju). @@ -26,7 +26,7 @@ To create a GitHub repository, log in to [GitHub](https://github.com) with your ### Activate GitHub APIs related to self-hosted runner -***This must be done for the GitHub runner charm to function correctly.*** +> ***⚠️ This must be done for the GitHub runner charm to function correctly.*** The GitHub runner charm relies on GitHub APIs for self-hosted runners. Some of the APIs will only be functional after a self-hosted runner registration token is requested for the repository for the first time. @@ -46,11 +46,11 @@ juju deploy github-runner --constraints="cores=4 mem=16G root-disk=20G virt-type Replacing the `` with the personal access token, and `` the GitHub account name and GitHub repository separated with `/`. -The `--constraints` option for the `juju deploy` sets the resource requirements for the juju machine hosting the charm application. This is used to accommodate different sizes of self-hosted runners. For details, refer to [Managing resource usage](https://charmhub.io/github-runner/docs/managing-resource-usage). +The `--constraints` option for the `juju deploy` sets the resource requirements for the Juju machine hosting the charm application. This is used to accommodate different sizes of self-hosted runners. For details, refer to [Managing resource usage](https://charmhub.io/github-runner/docs/managing-resource-usage). The `--storage` option mounts a juju storage to be used as the disk for LXD instances hosting the self-hosted runners. Refer [How to configure runner storage](https://charmhub.io/github-runner/docs/configure-runner-storage) for more information. -The charm performs various installation and configuration on startup. The charm might upgrade the kernel of the juju machine and reboot the juju machine. During reboot, the juju machine will go into the `down` state, this is a part of the normal reboot process and the juju machine should be restarted after a while. +The charm performs various installation and configuration on startup. The charm might upgrade the kernel of the Juju machine and reboot the Juju machine. During reboot, the Juju machine will go into the `down` state; this is a part of the normal reboot process and the Juju machine should be restarted after a while. Once the charm reaches active status, visit the runner page for the GitHub repository (`https://github.com/{OWNER}/{REPO}/settings/actions/runners`) according to the instructions [here](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/using-self-hosted-runners-in-a-workflow#viewing-available-runners-for-a-repository). A single new runner should be available as it is the default number of self-hosted runners created. @@ -93,4 +93,4 @@ The charm and the self-hosted runners can be removed with the following command: ```shell juju remove-application github-runner -``` \ No newline at end of file +```