From 44aeb130bf81dec1cb360db89c4ac2372d86e26c Mon Sep 17 00:00:00 2001 From: Erin Conley Date: Fri, 27 Sep 2024 10:50:51 -0400 Subject: [PATCH] Update tutorial (#383) * Update title (ISD-2381) Move away from "Quick start" and adopt the convention "Deploy X charm for the first time" * Add step to create Juju model (ISD-2383) * Update cleanup section * Add explicit check (ISD-2384) --- docs/tutorial/quick-start.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/docs/tutorial/quick-start.md b/docs/tutorial/quick-start.md index 0bc7971f8..488a3b224 100644 --- a/docs/tutorial/quick-start.md +++ b/docs/tutorial/quick-start.md @@ -1,4 +1,4 @@ -# Quick start +# Deploy the GitHub runner charm for the first time ## What you'll do @@ -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)). For more information about how to install and use Juju, see [Get started with Juju](https://juju.is/docs/olm/get-started-with-juju). @@ -32,6 +32,14 @@ The GitHub runner charm relies on GitHub APIs for self-hosted runners. Some of t The registration token can be requested by calling the [GitHub API](https://docs.github.com/en/rest/actions/self-hosted-runners?apiVersion=2022-11-28#create-a-registration-token-for-a-repository). Alternatively, it can also be requested by visiting the "New self-hosted runner" page for the repository (`https://github.com/{OWNER}/{REPO}/settings/actions/runners/new`). This can be done by following the instruction to the 4th step provided [here](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners#adding-a-self-hosted-runner-to-a-repository). +### Set up the tutorial model + +To easily clean up the resources and to separate your workload from the contents of this tutorial, set up a new Juju model with the following command. + +``` +juju add-model github-runner-tutorial +``` + ### Deploy the GitHub runner charm The charm requires a GitHub personal access token with `repo` access, which can be created following the instructions [here](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic). @@ -52,6 +60,8 @@ The `--storage` option mounts a juju storage to be used as the disk for LXD inst 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. +Monitor the deployment status using `juju status --watch 5s`. The deployment finishes when the status shows "Active". + 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. The charm will spawn new runners on a schedule. During this time, the charm will enter maintenance status. @@ -85,10 +95,10 @@ If the workflow failed at the `Set up runner` step with the following message: The repository setting does not comply with the best practice enforce by the charm. See [How to comply with repository policies](https://charmhub.io/github-runner/docs/repo-policy). -#### Removing the charm +### Clean up the environment -The charm and the self-hosted runners can be removed with the following command: +The Juju model, charm and the self-hosted runners can be removed with the following command: ```shell -juju remove-application github-runner +juju destroy-model --destroy-storage github-runner-tutorial ```