docs: Adjust the PAT documentation

[ZPascal]

Context of this PR: #170 (comment)

[ZPascal]

@polina-c FYI, I've adjusted the documentation inside this PR. I hope that helps you?

[polina-c]

Will check. Thank you!!!

[liby]

Hello, I apologize for the inconvenience, but I'm seeking some additional context regarding an issue I'm facing.

My workflow file contains the following relevant content:

- name: Push changes
  uses: ad-m/github-push-action@master
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}

This part of my workflow has not been modified, and the last successful run was on July 24th without any issues. However, today I encountered the following error while using ad-m/github-push-action:

remote: error: GH006: Protected branch update failed for refs/heads/main.        
remote: error: Changes must be made through a pull request.        
To https://github.com/openai-translator/bob-plugin-openai-translator.git
 ! [remote rejected] HEAD -> main (protected branch hook declined)

Initially, I thought the issue might be related to GitHub Token permissions. In the Repo Settings > Actions > General > Workflow permissions, I switched from "Read repository contents and packages permissions" to "Read and write permissions." After retrying, the problem was not resolved.

Upon searching for related issues in the repository, I found two closed issues. Since it was mentioned in an issue that pushing to a protected branch in your own repository requires a personal access token, and noticing there was this PR, I wanted to ask here to understand more context as I'm still quite puzzled:

1. I haven't modified the rules for the protected branch; they have always been the default. Why did this issue suddenly arise?
   

2. To resolve this issue, is my only option to use a PAT instead of GITHUB_TOKEN?

Any insight or guidance you can provide would be greatly appreciated. Thank you for your time.

[ZPascal]

Hi @liby,

1. I haven't modified the rules for the protected branch; they have always been the default. Why did this issue suddenly arise?

Unfortunately, the logs of the corresponding run are no longer available and I can no longer understand why it once worked. The standard GITHUB_TOKEN normally has no admin rights and therefore cannot bypass branch protection rules.

2. To resolve this issue, is my only option to use a PAT instead of GITHUB_TOKEN?

It's also possible to use a custom GitHub OAuth App to generate the admin-scoped token and to overtake it (impersonate).

Any insight or guidance you can provide would be greatly appreciated. Thank you for your time.

What do you need specifically? A tutorial how do you create the PAT and which permissions/ settings are required?

[liby]

Thank you for your prompt response.

Unfortunately, the logs of the corresponding run are no longer available and I can no longer understand why it once worked.

I can only speculate that there may have been some adjustments made by GitHub in the interim, such as automatically adding branch protection to the main branches of repositories, which might not have been present before July 24th. This is just a guess, as I don't have any concrete evidence to confirm the changes.

What do you need specifically? A tutorial how do you create the PAT and which permissions/ settings are required?

I have managed to resolve the issue by creating a Personal Access Token and using it in my workflow.

However, I am still unclear about one aspect: is it necessary to include the token: ${{ secrets.PAT }} in the actions/checkout step as shown below?

  - uses: actions/checkout@v3
    with:
      fetch-depth: 0
      token: ${{ secrets.PAT }}

From what I've gathered, this seems to be a crucial step when using PAT. Can you confirm that this is indeed necessary? Or if it's only necessary under certain conditions?

Thank you once again for your time and assistance.

[ZPascal]

Hi @liby,

I can only speculate that there may have been some adjustments made by GitHub in the interim, such as automatically adding branch protection to the main branches of repositories, which might not have been present before July 24th. This is just a guess, as I don't have any concrete evidence to confirm the changes.

That might be possible.

However, I am still unclear about one aspect: is it necessary to include the token: ${{ secrets.PAT }} in the actions/checkout step as shown below?

  - uses: actions/checkout@v3
    with:
      fetch-depth: 0
      token: ${{ secrets.PAT }}

Yes, from my side it's recommended. Otherwise, you mix two different tokens, and that is maybe not the best idea because the checkout action stores by default the first used token (default token is the GITHUB_TOKEN).

From what I've gathered, this seems to be a crucial step when using PAT. Can you confirm that this is indeed necessary? Or if it's only necessary under certain conditions?

Yes, I can confirm that, but theoretically, it's also possible to disable the token store functionally of the checkout action and then it's not necessary.