diff --git a/.github/readme/imgs/setup_workflow_permissions.dark.png b/.github/readme/imgs/setup_workflow_permissions.dark.png
new file mode 100644
index 00000000..3d8fcf91
Binary files /dev/null and b/.github/readme/imgs/setup_workflow_permissions.dark.png differ
diff --git a/.github/readme/imgs/setup_workflow_permissions.light.png b/.github/readme/imgs/setup_workflow_permissions.light.png
new file mode 100644
index 00000000..841a968c
Binary files /dev/null and b/.github/readme/imgs/setup_workflow_permissions.light.png differ
diff --git a/.github/readme/partials/documentation/setup/action.md b/.github/readme/partials/documentation/setup/action.md
index e504b732..ab9d1a02 100644
--- a/.github/readme/partials/documentation/setup/action.md
+++ b/.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:
diff --git a/source/app/web/statics/app.js b/source/app/web/statics/app.js
index 387b755d..54dfaa1a 100644
--- a/source/app/web/statics/app.js
+++ b/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:`,
diff --git a/source/plugins/core/README.md b/source/plugins/core/README.md
index bcd2b0e7..af012b52 100644
--- a/source/plugins/core/README.md
+++ b/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
-  with:
-    output_action: commit
-    committer_branch: metrics-renders
-    committer_message: "chore: update metrics"
+metrics:
+  permissions:
+    contents: write
+  steps:
+    - 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
-  with:
-    filename: my-metrics-0.svg
-    output_action: pull-request
+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
-  with:
-    filename: my-metrics-1.svg
-    output_action: pull-request-merge
+    - uses: lowlighter/metrics@latest
+      with:
+        filename: my-metrics-1.svg
+        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
-  with:
-    output_action: gist
-    committer_gist: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+metrics:
+  steps:
+    - uses: lowlighter/metrics@latest
+      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
-  uses: actions/checkout@v2
-    with:
-      fetch-depth: 0
+metrics:
+  permissions:
+    contents: write
+  steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
 
-- uses: lowlighter/metrics@latest
-  with:
-    output_action: none
+    - uses: lowlighter/metrics@latest
+      with:
+        output_action: none
 
-- uses: lowlighter/metrics@latest
-  run: |
-    set +e
-    git checkout metrics-renders
-    git config user.name github-actions[bot]
-    git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-    sudo mv /metrics_renders/* ./
-    git add --all
-    git commit -m "chore: push metrics"
-    git push
+    - uses: lowlighter/metrics@latest
+      run: |
+        set +e
+        git checkout metrics-renders
+        git config user.name github-actions[bot]
+        git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+        sudo mv /metrics_renders/* ./
+        git add --all
+        git commit -m "chore: push metrics"
+        git push
 ```
 
 ## ♻️ Retrying automatically failed rendering and output action