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,11 +248,15 @@ 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:
-  with:
+  permissions:
-    output_action: commit
+    contents: write
-    committer_branch: metrics-renders
+  steps:
-    committer_message: "chore: update metrics"
+    - uses: lowlighter/metrics@latest
+      with:
+        output_action: commit
+        committer_branch: metrics-renders
+        committer_message: "chore: update metrics"
 ```
 
 ### Using pull requests
@@ -257,15 +269,20 @@ 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:
-  with:
+  permissions:
-    filename: my-metrics-0.svg
+    contents: write
-    output_action: pull-request
+    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:
+      with:
-    filename: my-metrics-1.svg
+        filename: my-metrics-1.svg
-    output_action: pull-request-merge
+        output_action: pull-request-merge
 ```
 
 ### Using gists
@@ -277,10 +294,12 @@ 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:
-  with:
+  steps:
-    output_action: gist
+    - uses: lowlighter/metrics@latest
-    committer_gist: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+      with:
+        output_action: gist
+        committer_gist: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 ```
 
 ### Manual handling
@@ -290,25 +309,29 @@ They will be available under `/metrics_renders/{filename}` in the runner.
 
 *Example: generate outputs and manually push them*
 ```yaml
-- name: Checkout repository
+metrics:
-  uses: actions/checkout@v2
+  permissions:
-    with:
+    contents: write
-      fetch-depth: 0
+  steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
 
-- uses: lowlighter/metrics@latest
+    - uses: lowlighter/metrics@latest
-  with:
+      with:
-    output_action: none
+        output_action: none
 
-- uses: lowlighter/metrics@latest
+    - uses: lowlighter/metrics@latest
-  run: |
+      run: |
-    set +e
+        set +e
-    git checkout metrics-renders
+        git checkout metrics-renders
-    git config user.name github-actions[bot]
+        git config user.name github-actions[bot]
-    git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+        git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-    sudo mv /metrics_renders/* ./
+        sudo mv /metrics_renders/* ./
-    git add --all
+        git add --all
-    git commit -m "chore: push metrics"
+        git commit -m "chore: push metrics"
-    git push
+        git push
 ```
 
 ## ♻️ Retrying automatically failed rendering and output action