Add instructions on how to use the automatic GHA token

README.md

@@ -176,12 +176,34 @@ even more specific, you can specify a suffix to be added to the cache key via th
 
 ### 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 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 use an authorized token; luckily [GHA provides you with one automatically at each run](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication), you just need to 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 env variable that Composer supports](https://getcomposer.org/doc/articles/authentication-for-private-packages.md#authentication-using-the-composer-auth-environment-variable) 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 need to 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 secred 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.