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
canonical · Sep 17, 2024 · e3858e3 · e3858e3
1 parent ce408e1
commit e3858e3
Show file tree

Hide file tree

Showing 18 changed files with 62 additions and 64 deletions.
diff --git 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.
+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
@@ -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.
+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
@@ -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
@@ -11,5 +11,5 @@ juju config <APP_NAME> labels=<COMMA_SEPARATED_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
@@ -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 <APP_NAME> path=<PATH>
-```
+```
diff --git 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
@@ -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 <commit SHA>`, where `<commit SHA>` is the commit SHA of the approved commit. Once posted, the self-hosted runners will run the workflow for this commit.
+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 <commit SHA>`, where `<commit SHA>` 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
@@ -1,32 +1,32 @@
 # 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:
 
 ```shell
 juju deploy github-runner --constraints="cores=4 mem=16G root-disk=20G virt-type=virtual-machine" --config token=<TOKEN> --config path=<OWNER/REPO> --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:
 
 ```shell
 juju deploy github-runner --constraints="cores=4 mem=6G root-disk=30G virt-type=virtual-machine" --config token=<TOKEN> --config path=<OWNER/REPO> --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
@@ -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
@@ -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 <desired-controller-name>`
 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.
+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
@@ -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).
+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
@@ -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
@@ -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=<TOKEN> --config path=<OWNER/REPO>
 ```
 
-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.