docs(README.md): Describe how to use PAT token

[csikb]

Add detailed description on how to use PAT for Releases

name: Release

on:
  pull_request:
  merge_group:
  push:
    branches: [ main ]

permissions: read-all

jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
        with:
          fetch-depth: 0
          # When I didn't specify this, I got the following error (below)
          token: ${{ secrets.RELEASE_GITHUB_TOKEN }}

      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: lts/jod

      - run: npm install -g [email protected]

      - run: semantic-release
        env:
          GH_TOKEN: ${{ secrets.RELEASE_GITHUB_TOKEN }}

https://github.com/BSStudio/bss-web-admin-backend/actions/runs/17317813582/job/49164063483#step:5:16

The command "git push --dry-run --no-verify https://[secure]@github.com/{{repository}} HEAD:main" failed with the error message remote: Permission to {{repository}}.git denied to github-actions[bot].

[csikb]

Hi @babblebey, can I ask for a review and an approval for this PR?

I was working with semantic release, and I think this information was really crucial for creating Releases on GitHub

[travi]

thanks for the feedback here, @csikb. these details about how the workflow token impacts things can be confusing, so i'm very open to improving our guidance.

however, this pr currently differs from our current guidance on our documentation site: https://semantic-release.gitbook.io/semantic-release/recipes/ci-configurations/github-actions#pushing-package.json-changes-to-your-repository

this should only be an issue when using the git plugin, which we strongly discourage. when someone decides that is necessary, despite our guidance, there are multiple options. one is to provide a PAT to the checkout step so that it gets persisted through the process, like you've suggested. the other is to prevent the checkout credentials from being persisted, so the later provided token is able to be used.

i think it would be best to be consistent in our documentation. could we instead link to the documentation site from here? if we think some clarification there would be helpful, i'm open to that, but i think centralizing to a single message is valuable.

[travi]

thinking about this further, i think this highlights further why it is important to centralize this message to the documentation site. this situation arrises because of how git credentials are managed by a github actions workflow and how they can impact later commits. neither of those parts are related to the github plugin, which is what this repo is for. the git commits impact the git plugin and there is no plugin for using github actions as the ci context. if this makes sense to include anywhere, it might fit better with the git plugin. i think the most i can see including in this repo along the lines of a sidenote suggesting that someone might be likely to also be using actions if they are using github and that documentation for that context can be found in the doc site