[Docs]: Document fine-grained permissions necessary for access token

[Throne3d]

What would you like to see changed/added?

I'm using komac to submit an update to HWInfo64, but wanted to use GitHub's new fine-grained personal access tokens instead of granting broad access. It would be great to have an easy list of permissions necessary to use this tool!

After forking the winget-pkgs repo, and granting read/write access to contents and pull requests, the tool was able to create a branch but seems to fail when creating the pull request

What would you like to do with REALiX.HWiNFO 7.62?
[x] Pull request
[ ] Write to files
[ ] Quit
Failed to create pull request after 3 attempts.
Reason: {"message":"Resource not accessible by personal access token","documentation_url":"https://docs.github.com/rest/pulls/pulls#create-a-pull-request"}.

I'm new to the tool, so I'm not sure what the full list of permissions is that's necessary for each functionality, or what exactly is missing to ensure it can create the final pull request.

[dpprdan]

Could it be that these fine-grained permissions do not grant permission to open a PR in microsoft/winget-pkgs?

[Throne3d]

My guess is it indeed doesn't allow it, based on the description of the permission (it says it allows read-only access to public repos), but I'm not sure how to let it write to them - it didn't seem that I was able to add the winpkgs repo in the drop-down list.

[blampe]

@Throne3d does your fine-grained token belong to an organization? If so, try setting KMC_FRK_OWNER to the name of your GitHub organization. (I just ran into something similar in microsoft/winget-create#470.)

[teras]

Hello all.

Please, is it possible to write which permissions are required, even for the old-style token? I tried some (obvious for me) combinations but it failed with the message:

Failed to create branch from upstream default branch

[russellbanks]

Please, is it possible to write which permissions are required, even for the old-style token?

For the classic token, Komac v1 only requires the public_repo scope. The unreleased Komac v2 requires the public_repo and read_org scopes. I haven't done any testing yet for the fine-grained token.

I tried some (obvious for me) combinations but it failed with the message:
Failed to create branch from upstream default branch

This is a known issue that sometimes happens on Komac v1. It's been difficult to reproduce but Komac v2 is rewritten in an entirely different language and uses the GitHub GraphQL API rather than the Rest API so the issue won't be present there.

[teras]

@russellbanks Thank you for the reply.

You are right, I have the kind of issues you are describing. Actually the issue for me happens 100% of the time. Maybe I should open a new issue about it.

[russellbanks]

I've tried getting a fine-grained token to work and Komac v2 is able to fully create the manifests and commit but fails to create a pull request as you found @Throne3d. Looking around, it doesn't appear to be possible with the current state of fine-grained tokens - peter-evans/create-pull-request#1791 (comment). This may change in the future and I'll add it to the ReadMe if it does.

[jo-chemla]

The mentioned issue peter-evans/create-pull-request#1791 was closed 3 weeks ago, linking to this section on the doc for fine-grained PAT. Not sure if this can help komac which might be in first case, although a solution is suggested in the linked doc.

Pushing to a fork with fine-grained permissions
Using a fine-grained Personal Access Token (PAT) or GitHub App with push-to-fork can be achieved, but comes with some caveats.
When using push-to-fork, the action needs permissions for two different repositories. It needs contents: write for the fork to push the branch, and pull-requests: write for the parent repository to create the pull request.
There are two main scenarios:

• The parent and fork have different owners. In this case, it's not possible to create a token that is scoped to both repositories so different tokens must be used for each.
• The parent and fork both have the same owner (i.e. they exist in the same org). In this case, a single token can be scoped to both repositories, but the permissions granted cannot be different. So it would defeat the purpose of using push-to-fork, and you might as well just create the pull request directly on the parent repository.