From 38a881baecfd1cdd57807414c49bc99cd0ad2e7f Mon Sep 17 00:00:00 2001
From: Louis Brunner <louis.brunner.fr@gmail.com>
Date: Thu, 25 Jan 2024 14:50:01 +0000
Subject: [PATCH] docs: improve docs around "Resource not accessible by
 integration"

---
 README.md | 39 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 6686846..4083557 100644
--- a/README.md
+++ b/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/create-outputs@v0.0.0-fake
+      id: test
+    - uses: LouisBrunner/checks-action@v1.6.1
+      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`