Merge branch 'main' into ISD-1092-loki-alert-rules

config.yaml

@@ -93,6 +93,8 @@ options:
     description: >-
       The GitHub Personal Access Token for registering the self-hosted runners. The token requires
       'repo' scope for repository runners and 'repo' + 'admin:org' scope for organization runners.
+      For fine grained token scopes, see
+      https://charmhub.io/github-runner/docs/how-to-change-token.
   virtual-machines:
     type: int
     default: 1

docs/how-to/change-token.md

@@ -2,21 +2,18 @@
 
 This charm supports changing the [GitHub personal access token (PAT)](https://github.com/settings/tokens) used.
 
-## Personal access token scope
-
-To use this charm for GitHub repositories, the following scopes should be selected:
+## Changing the token
 
-- `repo`
+Create a new [GitHub Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
 
-To use this charm for GitHub organisations, the following scopes should be selected:
+An example classic token scope for repository use:
 
 - `repo`
-- `admin:org`
 
-## Changing the token
+For managing token scopes (fine-grained token), refer to (reference/token-scopes.md).
 
 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.
 
 ```shell
 juju config <APP_NAME> token=<TOKEN>
-```
+```

docs/index.md

@@ -66,6 +66,8 @@ Thinking about using the GitHub runner charm for your next project? [Get in touc
   1. [Configurations](reference/configurations.md)
   1. [COS Integration](reference/cos.md)
   1. [External Access](reference/external-access.md)
+  1. [Integrations](reference/integrations.md)
+  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)

docs/reference/token-scopes.md

@@ -0,0 +1,42 @@
+# Token scopes
+
+## Fine grained access token scopes
+
+### Organizational Runners
+
+The following are the permissions scopes required for the GitHub runners when registering as an
+organisational runner.
+
+Organisation:
+
+- Self-hosted runners: read & write
+
+Repository:
+
+- Administration: read
+- Contents: read
+- Pull requests: read
+
+### Repository Runners
+
+The following are the permissions scopes required for the GitHub runners when registering as an
+repository runner.
+
+- Contents: read
+- Metadata: read
+- Pull requests: read
+
+## Personal access token scopes
+
+### Organizational Runners
+
+To use this charm for GitHub organisations, the following scopes should be selected:
+
+- `repo`
+- `admin:org`
+
+### Repository Runners
+
+To use this charm for GitHub repositories, the following scopes should be selected:
+
+- `repo`

docs/tutorial/quick-start.md

@@ -36,6 +36,7 @@ The registration token can be requested by calling the [GitHub API](https://docs
 
 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).
 A user with `admin` access for the repository/org is required, otherwise, the repo-policy-compliance will fail the job.
+For information on token scopes, see [How to change GitHub personal access token](how-to/change-token.md).
 
 Once the personal access token is created, the charm can be deployed with:
 

src/charm_state.py

@@ -152,13 +152,13 @@ def from_charm(cls, charm: CharmBase) -> "GithubConfig":
         path_str = cast(str, charm.config.get(PATH_CONFIG_NAME, ""))
         if not path_str:
             raise CharmConfigInvalidError(f"Missing {PATH_CONFIG_NAME} configuration")
-        path = parse_github_path(path_str, runner_group)
+        path = parse_github_path(cast(str, path_str), cast(str, runner_group))
 
         token = cast(str, charm.config.get(TOKEN_CONFIG_NAME))
         if not token:
             raise CharmConfigInvalidError(f"Missing {TOKEN_CONFIG_NAME} configuration")
 
-        return cls(token=token, path=path)
+        return cls(token=cast(str, token), path=path)
 
 
 class VirtualMachineResources(NamedTuple):
@@ -326,8 +326,9 @@ def _parse_dockerhub_mirror(cls, charm: CharmBase) -> str | None:
         if not dockerhub_mirror:
             return None
 
+        dockerhub_mirror = cast(str, dockerhub_mirror)
         dockerhub_mirror_url = urlsplit(dockerhub_mirror)
-        if dockerhub_mirror is not None and dockerhub_mirror_url.scheme != "https":
+        if dockerhub_mirror_url.scheme != "https":
             raise CharmConfigInvalidError(
                 (
                     f"Only secured registry supported for {DOCKERHUB_MIRROR_CONFIG_NAME} "
@@ -357,7 +358,7 @@ def _parse_openstack_clouds_config(cls, charm: CharmBase) -> dict | None:
             return None
 
         try:
-            openstack_clouds_yaml = yaml.safe_load(openstack_clouds_yaml_str)
+            openstack_clouds_yaml = yaml.safe_load(cast(str, openstack_clouds_yaml_str))
         except yaml.YAMLError as exc:
             logger.error(f"Invalid {OPENSTACK_CLOUDS_YAML_CONFIG_NAME} config: %s.", exc)
             raise CharmConfigInvalidError(