Add docs about token permissions (#1829)

* add docs on token perms

* bump version

* Update with Contents:read

* nitpick change

charm/charmcraft.yaml

@@ -50,8 +50,7 @@ config:
       default: false
     github_token:
       description: >-
-        The token to use for comms with GitHub. This can be a PAT or a fine-grained token
-        with permissions to read collaborators (and collaborators' permissions) and branches 
-        for all repositories that need to be checked.
-      type: string
-      required: true
+        The token to use for communication with GitHub. This can be a PAT (with repo scope)
+        or a fine-grained token with read permission for Administration. If private repositories 
+        are checked, the fine-grained token does also need read permission for Contents and 
+        Pull request.

charm/docs/reference/token-permissions.md

@@ -0,0 +1,20 @@
+# GitHub Token Permissions
+
+You can either choose to use a personal access token (PAT) or a fine-grained access token for the 
+`github_token` configuration. The token permissions/scopes are different for each type of token.
+
+
+## Fine grained access token permissions
+
+**Note**: In addition to having a token with the necessary permissions, the user who owns the
+token also must have admin access to the organisation or repository.
+
+For fine-grained access control, the following repository permissions are required:
+
+- Administration: read
+- Contents: read (if you want to check private repositories)
+- Pull requests: read (if you want to check private repositories)
+
+## Personal access token scopes
+
+If you want to use classic PATS, you will need to select the `repo` scope.

pyproject.toml

@@ -3,7 +3,7 @@
 
 [tool.poetry]
 name = "repo-policy-compliance"
-version = "1.9.1"
+version = "1.9.2"
 description = "Checks GitHub repository settings for compliance with policy"
 authors = ["Canonical IS DevOps <launchpad.net/~canonical-is-devops>"]
 license = "Apache 2.0"

rockcraft.yaml

@@ -3,7 +3,7 @@
 
 name: repo-policy-compliance
 base: [email protected]
-version: '1.9.1'
+version: '1.9.2'
 summary: Check the repository setup for policy compliance
 description: |
     Used to check whether a GitHub repository complies with expected policies.