Document custom PAT creation

Author: kdeldycke

.github/workflows/changelog.yaml

@@ -184,9 +184,8 @@ jobs:
           git commit --all --message="[changelog] Post-release version bump"
       - uses: peter-evans/create-pull-request@v6.0.0
         with:
-          # WORKFLOW_UPDATE_GITHUB_PAT is a custom token created from my user's profile via the
-          # "Developer Settings > Personal Access Tokens" UI to allow this job to update its own workflows. This is
-          # only used on the original kdeldycke/workflows repository, hence the fallback to default GitHub token.
+          # We need custom PAT with workflows permission to hard-code version numbers in URLs in
+          # .github/workflows/*.yaml files.
           token: ${{ secrets.WORKFLOW_UPDATE_GITHUB_PAT || secrets.GITHUB_TOKEN }}
           assignees: ${{ github.actor }}
           title: >

.github/workflows/docs.yaml

@@ -32,9 +32,7 @@ jobs:
         run: rm ./typos
       - uses: peter-evans/create-pull-request@v6.0.0
         with:
-          # WORKFLOW_UPDATE_GITHUB_PAT is a custom token created from my user's profile via the
-          # "Developer Settings > Personal Access Tokens" UI to allow this job to update its own workflows. This is
-          # only used on the original kdeldycke/workflows repository, hence the fallback to default GitHub token.
+          # We need custom PAT with workflows permissions to fix typos in .github/workflows/*.yaml` files.
           token: ${{ secrets.WORKFLOW_UPDATE_GITHUB_PAT || secrets.GITHUB_TOKEN }}
           assignees: ${{ github.actor }}
           commit-message: "[autofix] Typo"

.github/workflows/release.yaml

@@ -199,10 +199,7 @@ jobs:
         if: ${{ ! steps.tag_exists.outputs.tag_exists }}
         uses: tvdias/github-tagger@v0.0.2
         with:
-          # XXX actionlint triggers this error:
-          #   property "workflow_update_github_pat" is not defined in object type {actions_runner_debug: string;
-          #   actions_step_debug: string; github_token: string; pypi_token: string} [expression]
-          # See: https://github.com/rhysd/actionlint/issues/148
+          # XXX We need custom PAT with workflows permissions BECAUSE ??? in .github/workflows/*.yaml files.
           repo-token: ${{ secrets.WORKFLOW_UPDATE_GITHUB_PAT || secrets.GITHUB_TOKEN }}
           tag: v${{ matrix.current_version }}
           commit-sha: ${{ matrix.commit }}
@@ -304,6 +301,7 @@ jobs:
       - name: Create GitHub release
         uses: softprops/action-gh-release@v1
         env:
+          # XXX We need custom PAT with workflows permissions BECAUSE ??? in .github/workflows/*.yaml files.
           GITHUB_TOKEN: ${{ secrets.WORKFLOW_UPDATE_GITHUB_PAT || secrets.GITHUB_TOKEN }}
         with:
           tag_name: v${{ matrix.current_version }}

readme.md

@@ -47,8 +47,22 @@ You will always end up with this kind or errors:
 To bypass the limitation, we rely on a custom access token. By convention, we call it `WORKFLOW_UPDATE_GITHUB_PAT`. It will be used, [in place of the default `secrets.GITHUB_TOKEN`](https://github.com/search?q=repo%3Akdeldycke%2Fworkflows%20WORKFLOW_UPDATE_GITHUB_PAT&type=code), in steps in which we need to change the workflow YAML files.
 
 To create this custom `WORKFLOW_UPDATE_GITHUB_PAT`:
-- Go to your GitHub user's profile via the `Developer Settings` > `Personal Access Tokens` UI
-          
+- From your GitHub user, go to `Settings` > `Developer Settings` > `Personal Access Tokens` > `Fine-grained tokens`
+- Click on the `Generate new token` button
+- Choose a good token name like `workflow-self-update` to make your intention clear
+- Choose `Only select repositories` and the list the repositories in needs of updating their workflow YAML files
+- In the `Repository permissions` drop-down, sets:
+  - `Contents`: `Access: **Read and Write**`
+  - `Metadata` (mandatory): `Access: **Read-only**`
+  - `Pull Requests`: `Access: **Read and Write**`
+  - `Workflows`: `Access: **Read and Write**`
+    > [!NOTE]
+    > This is the only place where I can have control over the `Workflows` permission, which is not supported by the `permissions:` parameter in YAML files.
+- Now save these parameters and copy the `github_pat_XXXX` secret token
+- Got to your repo > `Settings` > `Security` > `Secrets and variables` > `Actions` > `Secrets` > `Repository secrets` and click `New repository secrets`
+- Name your secret `WORKFLOW_UPDATE_GITHUB_PAT` and copy the `github_pat_XXXX` token in the `Secret` field
+
+Now re-run your actions and they should be able to update the workflow files in `.github` folder without the `refusing to allow a GitHub App to create or update workflow` error.
 
 ## Release management