docs: notice about token permissions and usage (relates #1050, #1076)

.github/readme/partials/documentation/setup/action.md

@@ -16,6 +16,8 @@ Its `README.md` will be displayed on your user profile:
 
 ## 1️ Create a GitHub personal token
 
+> 💡 A GitHub personal token is required since this action will fetch data that cannot be accessed through repository-scoped tokens (like [`${{ secrets.GITHUB_TOKEN }}` or `${{ github.token }}`](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#about-the-github_token-secret)) such as users, organizations, issues, pull requests, comments, commits, activity, etc.
+
 From the `Developer settings` of your account settings, select `Personal access tokens` to create a new token.
 
 No scopes are required, but additional one may be required depending on which features will be used. Each plugin documentation enumerates which scopes are required to make it work.
@@ -65,17 +67,21 @@ on:
 jobs:
   github-metrics:
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
       - uses: lowlighter/metrics@latest
         with:
           token: ${{ secrets.METRICS_TOKEN }}
 ```
 
-Rendered metrics will be committed to repository on each run.
+Default output action is to commit rendered metrics to target repository on each run.
 
 ![Action update example](/.github/readme/imgs/example_action_update.light.png#gh-light-mode-only)
 ![Action update example](/.github/readme/imgs/example_action_update.dark.png#gh-dark-mode-only)
 
+Use [`output_action`](/source/plugins/core/README.md#-configuring-output-action) to change this behaviour to use either pull requests, gists or manually handle renders.
+
 ### 3️.1️ Choosing between `@latest`, `@master`/`@main`, a fork or a pinned version
 
 There are several *metrics* versions that can be used in workflows:

source/app/web/statics/app.js

@@ -214,6 +214,8 @@
           `jobs:`,
           `  github-metrics:`,
           `    runs-on: ubuntu-latest`,
+          `    permissions:`,
+          `      contents: write`,
           `    steps:`,
           `      - uses: lowlighter/metrics@latest`,
           `        with:`,

source/plugins/core/README.md

@@ -231,6 +231,14 @@ It is possible to generate a self-contained HTML file containing `✨ Metrics in
 
 ## 🧶 Configuring output action
 
+Before configuring output action, ensure that workflows permissions are properly set.
+These can be changed either through repository settings in Actions tab:
+
+![Setting workflows permissions](/.github/readme/imgs/setup_workflow_permissions.light.png#gh-light-mode-only)
+![Setting workflows permissions](/.github/readme/imgs/setup_workflow_permissions.dark.png#gh-dark-mode-only)
+
+Or more granulary [at job or workflow level](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token).
+
 ### Using commits (default)
 
 Use `config_output: commit` to make the action directly push changes to `committer_branch` with a commit.
@@ -240,7 +248,11 @@ A custom commit message can be used through `committer_message`.
 
 *Example: push output to metrics-renders branch rather than the default branch*
 ```yaml
-- uses: lowlighter/metrics@latest
+metrics:
+  permissions:
+    contents: write
+  steps:
+    - uses: lowlighter/metrics@latest
       with:
         output_action: commit
         committer_branch: metrics-renders
@@ -257,12 +269,17 @@ The last step should use either `pull-request-merge`, `pull-request-squash` or `
 
 *Example: push two outputs using a merge pull request*
 ```yaml
-- uses: lowlighter/metrics@latest
+metrics:
+  permissions:
+    contents: write
+    pull-requests: write
+  steps:
+    - uses: lowlighter/metrics@latest
       with:
         filename: my-metrics-0.svg
         output_action: pull-request
 
-- uses: lowlighter/metrics@latest
+    - uses: lowlighter/metrics@latest
       with:
         filename: my-metrics-1.svg
         output_action: pull-request-merge
@@ -277,7 +294,9 @@ It is required to provide a gist id to `committer_gist` option to make it work.
 
 *Example: push output to a gist*
 ```yaml
-- uses: lowlighter/metrics@latest
+metrics:
+  steps:
+    - uses: lowlighter/metrics@latest
       with:
         output_action: gist
         committer_gist: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
@@ -290,16 +309,20 @@ They will be available under `/metrics_renders/{filename}` in the runner.
 
 *Example: generate outputs and manually push them*
 ```yaml
-- name: Checkout repository
+metrics:
+  permissions:
+    contents: write
+  steps:
+    - name: Checkout repository
       uses: actions/checkout@v2
         with:
           fetch-depth: 0
 
-- uses: lowlighter/metrics@latest
+    - uses: lowlighter/metrics@latest
       with:
         output_action: none
 
-- uses: lowlighter/metrics@latest
+    - uses: lowlighter/metrics@latest
       run: |
         set +e
         git checkout metrics-renders