Update docs for fine-grained GitHub tokens

[sheerlox]

Description

Following my exchange with @travi on GitHub's "Fine-grained personal access tokens" discussion, here's an issue to keep track of the notes I took, changes to be made, and to ask/receive feedback. Please let me know if I forgot anything!

Important points

• When using GitHub Actions, this is only necessary when using branch protection, otherwise, using the permissions feature in workflows as described in the GitHub Actions documentation is enough.
• When pushing to GitHub from other CI tools, using fine-grained PAT will increase the security in contrast to using a regular PAT (regardless of branch protection settings).
• Make clear that using a PAT is only needed to bypass branch protection, which is not relevant when not using @semantic-release/git (update documentation to more clearly discourage use of this plugin #477)

Documentations to be updated

• usage/ci-configuration#authentication

  • update the GH_TOKEN variable descriptions
  • add a section specifically for GitHub PAT (regular vs fine-grained) explaining the functioning and the security enhancements over regular PAT

• recipes/ci-configurations/github-actions#pushing-package.json-changes-to-a-master-branch

  • update the note about using a PAT to circumvent branch protection settings
  • add a link to the newly added "GitHub PAT" section

• semantic-release/git README > Git authentication

  • add a link to the newly added "GitHub PAT" section
  • add required fine-grained scopes for the plugin

• semantic-release/github README > GitHub authentication

  • add a link to the newly added "GitHub PAT" section
  • add required fine-grained scopes for the plugin

Resources

• StackOverflow - "Github: Pushing to protected branches with fine-grained token"

Feedback wanted

• should we create the "GitHub PAT" section outside the CI configurations dropdown? if so, where do you think would be the most appropriate?

[travi]

sorry for the delayed response here. you caught me while i was traveling and i've been slow to catch up. thanks a lot for digging in and taking an organized approach to this :)

• When using GitHub Actions, this is only necessary when using branch protection, otherwise, using the permissions feature in workflows as described in the GitHub Actions documentation is enough.

this is definitely an area that would be great to add clarity to. one aspect that has been on my mind in this area that we should probably touch on is the new repository rules functionality. this provides some options for enabling certain users to bypass protection rules at a more granular level than before, so it is no longer required to use an admin account to do these automated pushes. up to you if this sort of detail is included in initial iterations, but i think there would be value if someone could touch on this aspect at some point.

• should we create the "GitHub PAT" section outside the CI configurations dropdown? if so, where do you think would be the most appropriate?

something i continue to struggle with around the organization of our documentation is when to provide the depth in the documentation site vs in the readme of individual plugins, so that feels like the first decision to make. i havent given this a lot of thought yet, but this topic feels related to both the git and github plugins, so i think your lean to put in in the documentation site and link to it from the plugin readmes seems appropriate.

i do also wonder if the recommendations change between folks that use the git + github plugins vs only the github plugin

as far was where makes the most sense within the docs site, updates to https://semantic-release.gitbook.io/semantic-release/usage/ci-configuration#push-access-to-the-remote-repository, and possibly the note at the bottom of that page, feel the most natural to me. happy to be convinced of a different location if you have something else in mind

[sheerlox]

sorry for the delayed response here. you caught me while i was traveling and i've been slow to catch up

no problem at all, hope you enjoyed your vacation, personal time is important ;)

one aspect that has been on my mind in this area that we should probably touch on is the new repository rules functionality. this provides some options for enabling certain users to bypass protection rules at a more granular level than before, so it is no longer required to use an admin account to do these automated pushes. up to you if this sort of detail is included in initial iterations, but i think there would be value if someone could touch on this aspect at some point.

I wasn't aware of that new feature! that's great news, I'll definitely need to dig into it as soon as I can to include this in the PR since documenting a more secure approach right from the start seems to be the best choice.

i do also wonder if the recommendations change between folks that use the git + github plugins vs only the github plugin

fine-grained scopes required for each plugin differ, the git plugin only needs write access to Contents, while the GitHub one additionally needs write access to Issues & Pull requests, but apart from that I'm not aware of notable differences.

as far was where makes the most sense within the docs site, updates to https://semantic-release.gitbook.io/semantic-release/usage/ci-configuration#push-access-to-the-remote-repository, and possibly the note at the bottom of that page, feel the most natural to me. happy to be convinced of a different location if you have something else in mind

I think agree with you, maybe we can add a section right under (or within?) "Push access to the remote repository" specific to GitHub authentication?

[sheerlox]

cf. ossf/scorecard documentation on the same subject: https://github.com/ossf/scorecard-action/blob/main/docs/authentication/fine-grained-auth-token.md#authentication-with-fine-grained-pat-optional

[travi]

worth considering this as part of this effort too: #477

[sheerlox]

After setting up private Renovate instances for @talent-ideal and @insurgent-lab as GitHub Actions using a GitHub App to authenticate, and learning more about the repository rulesets, I realized this could be the best solution.

I haven't had the time to setup a test repository and check if that would work, but semantic-release/semantic-release#1807 states that GitHub App installation tokens are supported by semantic-release.

[travi]

i agree that suggesting use of repository rules is likely the best suggestion rather than branch protection. i think we will have to continue to provide information on multiple options for a while, but making a clear recommendation and possibly linking to external sources for backing or additional detail could be helpful

[travi]

to frame the higher level goal, i would really like a place in the docs to link to for expanding on what i explained in semantic-release/semantic-release#2604 (comment). that likely goes beyond the focus on fine-grained tokens, but i think it is worth keeping in mind as we approach the smaller steps

[sheerlox]

Just realized that since branch protection is only an issue for @semantic-release/git, we might be fine simply adding a PAT section on its README. Can you transfer the issue there if you agree?

[travi]

so sorry that i havent followed up on this. i agree that the complexity largely lies there, so i think it is the best place to focus to start, at the very least