docs: improve docs around "Resource not accessible by integration" (#257

)

README.md

@@ -6,7 +6,7 @@ This GitHub Action allows you to create [Check Runs](https://developer.github.co
 
 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 @@ jobs:
 
 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`