docs: document authentication methods

Author: hanna-skryl

README.md

@@ -84,6 +84,36 @@ retain report artifacts for 30 days:
     retention: 30
 ```
 
+## Authentication
+
+The GitHub Action supports multiple authentication methods to integrate with
+your CI workflows.
+
+### GitHub App authentication (recommended)
+
+For the most seamless authentication experience, we recommend installing the
+[Code PushUp GitHub App](https://github.com/apps/code-pushup-staging).
+
+The action automatically detects the GitHub App installation and uses it for
+enhanced API access. This provides better security through short-lived tokens
+and requires zero configuration on your part.
+
+### Default authentication
+
+If the GitHub App is not installed, the action automatically uses the default
+`GITHUB_TOKEN` provided by GitHub Actions, which works perfectly for most use
+cases.
+
+### Custom authentication
+
+You can provide your own token if you have specific requirements:
+
+```yml
+- uses: code-pushup/github-action@v0
+  with:
+    token: ${{ secrets.YOUR_PAT }}
+```
+
 ## Action outputs
 
 Some outputs are set in case you want to add further steps to your workflow.