Merge pull request #1241 from mikepenz/fix/1230

Clarify documentation on local testing | Token permissions

README.md

@@ -554,21 +554,27 @@ export GITHUB_TOKEN=your_personal_github_pat
 
 ## Local Testing 🧪 
 
-This GitHub action is fully developed in Typescript and can be run locally via npm. Doing so is a great way to test the action and/or your custom configurations locally, without the need to push and re-run GitHub actions over and over again.
+This GitHub action is fully developed in Typescript and can be run locally via npm or right from the browser using GitHub Codespace. 
 
-To run this action locally, first make sure you provide a `GITHUB_TOKEN` with enough permissions to access the repository. 
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/mikepenz/release-changelog-builder-action)
+
+Doing so is a great way to test the action and/or your custom configurations locally, without the need to push and re-run GitHub actions over and over again.
+
+To run locally, or to access private repositories (GitHub Codespaces has automatic access to public repos with the default token), you will require to provide a valid `GITHUB_TOKEN` with read only permissions to access the repositories you want to run this action towards. (See more details in [Token Permission](#Token-Permission))
 
 ```
-# GitHub token for the action
+# Export the token in the CLI you use to execute.
 export GITHUB_TOKEN=your_read_only_github_token
 ```
 
-Afterwards run the testcases with:
+Afterwards it is possible to run the tests included in the project:
 
 ```bash
-npm test -- custom.test.ts
+npm test -- main.test.ts # modify the file name to run other testcases
 ```
 
+To test your own configuration, it's adviced to create a new `__tests__/custom.test.ts` file, modify it to your needs (e.g. change repo, change token, change settings, ...), and then run it via `npm test -- custom.test.ts`
+
 <details><summary><b>custom.test.ts</b></summary>
 <p>
 
@@ -607,15 +613,32 @@ it('Test custom changelog builder', async () => {
 
   const changeLog = await releaseNotesBuilder.build()
   console.log(changeLog)
-  expect(changeLog).toStrictEqual(`define-expected-output`)
 })
 ```
 
 </p>
 </details>
 
-Additionally it is possible to do full debugging including the option of breakpoints via (for example) Visual Code. 
-Open the project in Visual code -> open the terminal -> use the `+` and start a new `JavaScript Debug Terminal`. Afterwards run the tests as described above. 
+One major benefit of setting up a custom test is that it will allow you to use javascripts full debugging support, including the option of breakpoints via (for example) Visual Code. 
+
+From GitHub codespaces, open the terminal panel -> Click the small arrow down beside `+` and pick `JavaScript Debug Terminal` (make sure to export the token again). Now execute the test with this terminal. (This is very similar to local Visual Code environments).
+
+## Token Permission
+
+Permissions depend on the specific usecase, however this action only requires `read-only` permissions as it will not make modifications to the repository.
+
+For `Fine-grained personal access tokens` this means:
+
+- `read` for [Pull requests](https://github.com/mikepenz/release-changelog-builder-action/blob/develop/pr-collector/src/pullRequests.ts#L124)
+  - Covered by the `pull-requests` scope
+- `read` for [Commits](https://github.com/mikepenz/release-changelog-builder-action/blob/develop/pr-collector/src/commits.ts#L54) 
+  - Covered by the `contents` scope
+- `read` for [Tags](https://github.com/mikepenz/release-changelog-builder-action/blob/develop/pr-collector/src/tags.ts#L32) (if not available the `from` and `to` refs have to be provided)
+  - Covered by the `contents` scope
+- `read` to [list reviews](https://github.com/mikepenz/release-changelog-builder-action/blob/develop/pr-collector/src/pullRequests.ts#L186)
+  - Covered by the `contents` scope
+ 
+ For Classic tokens you only have to create the token without special permissions.
 
 ## Developed By
 
@@ -638,13 +661,13 @@ Open the project in Visual code -> open the terminal -> use the `+` and start a
 ## License
 
     Copyright for portions of pr-release-notes are held by Nikolay Blagoev, 2019-2020 as part of project pull-release-notes.
-    All other copyright for project pr-release-notes are held by Mike Penz, 2021.
+    All other copyright for project pr-release-notes are held by Mike Penz, 2023.
 
 ## Fork License
 
 All patches and changes applied to the original source are licensed under the Apache 2.0 license.
 
-    Copyright 2022 Mike Penz
+    Copyright 2023 Mike Penz
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.