docs: improve docs around "Resource not accessible by integration"

README.md

@@ -1,12 +1,12 @@
 # GitHub Actions: `checks-action` ![build-test](https://github.com/LouisBrunner/checks-action/workflows/build-test/badge.svg)
 
 This GitHub Action allows you to create [Check Runs](https://developer.github.com/v3/checks/runs/#create-a-check-run) directly from your GitHub Action workflow. While each job of a workflow already creates a Check Run, this Action allows to include `annotations`, `images`, `actions` or any other parameters supported by the [Check Runs API](https://developer.github.com/v3/checks/runs/#parameters).
 
 ## Usage
 
 The following shows how to publish a Check Run which will have the same status as your job and contains the output of another action. This will be shown predominantly in a Pull Request or on the workflow run.
 
-```
+```yaml
 name: "build-test"
 on: [push]
 
@@ -29,6 +29,43 @@
 
 See the [examples workflow](.github/workflows/examples.yml) for more details and examples (and see the [associated runs](https://github.com/LouisBrunner/checks-action/actions?query=workflow%3Aexamples) to see how it will look like).
 
+### Permissions
+
+When the action is run as part of a Pull Request, your workflow might fail with the following error: `Error: Resource not accessible by integration`.
+
+You can solve this in multiple ways:
+
+* Increase the permissions given to `GITHUB_TOKEN` (see https://github.com/actions/first-interaction/issues/10#issuecomment-1232740076), please note that you should understand the security implications of this change
+* Use a Github App token instead of a `GITHUB_TOKEN` (see https://github.com/LouisBrunner/checks-action/issues/26#issuecomment-1232948025)
+
+Most of the time, it means setting up your workflow this way:
+
+```yaml
+name: "build-test"
+on: [push]
+
+jobs:
+  test_something:
+    runs-on: ubuntu-latest
+    permissions:
+      checks: write
+      contents: read
+    steps:
+    - uses: actions/checkout@v1
+    - uses: actions/[email protected]
+      id: test
+    - uses: LouisBrunner/[email protected]
+      if: always()
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+        name: Test XYZ
+        conclusion: ${{ job.status }}
+        output: |
+          {"summary":"${{ steps.test.outputs.summary }}"}
+```
+
+Notice the extra `permissions` section.
+
 ## Inputs
 
 ### `repo`