Add instructions on how to use the automatic GHA token (#263)

Co-authored-by: Ben Ramsey <ben@ramsey.dev>

Author: Jean85

README.md

@@ -209,14 +209,54 @@ execution if it does not find a lock file.
 
 ### Fork and private repositories
 
-Sometimes it's needed to use the `repositories` key in your `composer.json` to pull in forks, PRs with patches or private repositories. In this case, your GitHub Action may start failing with a `Could not authenticate against github.com` error message. To solve this, you need to add a GitHub Personal Access token, and this bit to your Action configuration:
+Sometimes it's necessary to use the `repositories` key in your `composer.json` to
+pull in forks, PRs with patches, or private repositories. In this case, your
+GitHub Action may start failing with a `Could not authenticate against github.com`
+error message. To solve this, you need to use an authorized token. Luckily,
+[GHA provides you with one automatically at each run][]; all you need to do is
+set the `repository-projects` permission to `read`:
+
+```yaml
+job:
+  permissions:
+    repository-projects: read
+  steps:
+  # ...
+  - uses: ramsey/composer-install@v3
+    env:
+      COMPOSER_AUTH: '{"github-oauth": {"github.com": "${{ secrets.GITHUB_TOKEN }}"}}'
+```
+
+In the example above, `COMPOSER_AUTH` is the [default environment variable that Composer supports][]
+to dynamically configure its authentication. If you have other authentication tokens
+in use, and you don't want to conflict with those, you can record the token
+programmatically, as in the example below:
+
+```yaml
+job:
+  permissions:
+    repository-projects: read
+  steps:
+  # ...
+  - run: composer config -- github-oauth.github.com ${{ secrets.GITHUB_TOKEN }}
+    name: Register GitHub token for Composer
+  - uses: ramsey/composer-install@v3
+```
+
+Note that this approach is only valid for public forks; if you need to access
+private repositories, you must create a secret in the repository that runs the
+action, and use it to store a Personal Access Token with a `read:project` scope
+from a user that is allowed to read those repositories, and use in place of
+`secrets.GITHUB_TOKEN`. In the following example, the PAT is stored in a secret
+called `COMPOSER_PAT`:
+
 ```yaml
 env:
-   COMPOSER_AUTH: '{"github-oauth": {"github.com": "${{ secrets.COMPOSER_AUTH }}"}}'
+  COMPOSER_AUTH: '{"github-oauth": {"github.com": "${{ secrets.COMPOSER_PAT }}"}}'
 ```
-In this example, `COMPOSER_AUTH` is the name of the secret that you'll need to create. To access public repositories, the `public_repo` scope is sufficient, while for private repositories (that you can access), `read:project` will be needed.
 
-For more information on how to do that on your repository, see [Creating a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) and [Creating encrypted secrets for a repository](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) on GitHub documentation.
+For more information on how to do that on your repository, see [Creating a personal access token][]
+and [Creating encrypted secrets for a repository][] on GitHub documentation.
 
 ### Matrix Example
 
@@ -263,3 +303,9 @@ yourself with [CONTRIBUTING.md](CONTRIBUTING.md).
 The ramsey/composer-install GitHub Action is copyright © [Ben Ramsey](https://benramsey.com)
 and licensed for use under the terms of the MIT License (MIT). Please see
 [LICENSE](LICENSE) for more information.
+
+
+[GHA provides you with one automatically at each run]: https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication
+[default environment variable that Composer supports]: https://getcomposer.org/doc/articles/authentication-for-private-packages.md#authentication-using-the-composer-auth-environment-variable
+[Creating a personal access token]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
+[Creating encrypted secrets for a repository]: https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository