From 385a9fc5301803f63cdfde94d63feb256736e63e Mon Sep 17 00:00:00 2001
From: Peter Serwylo <peter.serwylo@anz.com>
Date: Thu, 22 Dec 2022 12:24:14 +1100
Subject: [PATCH] Add documentation for using GitHub App Installation tokens
 instead of personal access tokens.

Identified this while using an app installation token locally and working through the code.
It seems that the use case for GitHub App Installations is currently only for specifically
running from within GitHub Actions, which sets GITHUB_TOKEN rather than GH_TOKEN. However,
it is possible that other CI tools make use of GitHub App Installation tokens, and thus they
also require the same treatment.

This could be fixed in the code to be more explicit, but for now hopefully the documentation
change is helpful to some.
---
 README.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 3f87d33f..9319817c 100644
--- a/README.md
+++ b/README.md
@@ -74,6 +74,12 @@ When using the _GITHUB_TOKEN_, the **minimum required permissions** are:
 | `GITHUB_API_URL` or `GH_URL` or `GITHUB_URL`       | The GitHub Enterprise endpoint.                           |
 | `GH_PREFIX` or `GITHUB_PREFIX`                     | The GitHub Enterprise API prefix.                         |
 
+#### Using GitHub App Installation tokens
+
+If the token you are using is from a GitHub App Installation instead of a Personal Access Token,
+then you must use `GITHUB_TOKEN` instead of `GH_TOKEN` and set `GITHUB_ACTION=true` in your environment prior to running.
+[See `get-git-auth-url` for details](https://github.com/semantic-release/semantic-release/blob/fa241a2a06b593d1a04cb0af07ee31acd5b3cae8/lib/get-git-auth-url.js#L65-L67]).
+
 ### Options
 
 | Option                | Description                                                                                                                                                                                            | Default                                                                                                                                              |
@@ -218,4 +224,4 @@ Valid values for this option are `false`, `"top"` or `"bottom"`.
 
 ##### addReleases example
 
-See [The introducing PR](https://github.com/semantic-release/github/pull/282) for an example on how it will look.
\ No newline at end of file
+See [The introducing PR](https://github.com/semantic-release/github/pull/282) for an example on how it will look.