search

semantic-release / git

:twisted_rightwards_arrows: semantic-release plugin to commit release assets to the project's git repository
MIT License
304 stars 68 forks source link

Update docs for fine-grained GitHub tokens #509

Open sheerlox opened 1 year ago

sheerlox commented 1 year ago

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

Documentations to be updated

Resources

Feedback wanted

travi commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

worth considering this as part of this effort too: https://github.com/semantic-release/git/issues/477

sheerlox commented 1 year ago

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 https://github.com/semantic-release/semantic-release/issues/1807 states that GitHub App installation tokens are supported by semantic-release.

travi commented 1 year ago

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 commented 1 year ago

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 https://github.com/semantic-release/semantic-release/issues/2604#issuecomment-1802167534. 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 commented 1 year ago

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 commented 8 months ago

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