Clarify permissions needed for auto-merge (`--pr-merge`)

[MPV]

Hi,
Could we clarify the permissions needed for auto-merge (--pr-merge), as described here:

--pr-merge (bool): if enabled, the Pull Requests will be automatically merged. It will wait until the PRs are “mergeable” before merging them. Default to false.

-- https://dailymotion-oss.github.io/octopilot/v1.5.3/index.html#merging-pull-requests

I'm running it using a GitHub App myself, but I imagine the same permission model might apply to personal access tokens (PAT).

[MPV]

For example, before I realized I needed to grant repository admin view permissions, I got errors like this:

failed to retrieve the required status checks for branch master: GET https://api.github.com/repos/my-org/my-repo/branches/master/protection/required_status_checks: 403 Resource not accessible by integration []

...as seen in this excerpt:

[...]
time="2023-11-20T08:21:25Z" level=debug msg="Pull Request is mergeable" pull-request="https://github.com/my-org/my-repo/pull/16" repository=my-org/my-repo
time="2023-11-20T08:21:25Z" level=error msg="Repository update failed" error="failed to merge Pull Request https://github.com/my-org/my-repo/pull/16: failed to wait until Pull Request https://github.com/my-org/my-repo/pull/16 is mergeable: failed to retrieve the required status checks for branch master: GET https://api.github.com/repos/my-org/my-repo/branches/master/protection/required_status_checks: 403 Resource not accessible by integration []" repository=my-org/my-repo

...likely related to this issue:

• Don't require Administration permissions to view Branch Protection Settings isaacs/github#1940

[MPV]

But now when I've granted "repo admin view" permissions, I instead get this error (which I've yet to find the permission for):

failed to retrieve combined status of Pull Request https://github.com/my-org/my-repo/pull/3 for ref 0e5f7f8ce0e2372dbf53ce955223e8ac2e5c4b73: GET https://api.github.com/repos/my-org/my-repo/commits/0e5f7f8ce0e2372dbf53ce955223e8ac2e5c4b73/status: 403 Resource not accessible by integration []

...as seen in this excerpt:

time="2023-11-20T08:33:15Z" level=debug msg="Pull Request is mergeable" pull-request="https://github.com/my-org/my-repo/pull/3" repository=my-org/my-repo
time="2023-11-20T08:33:16Z" level=error msg="Repository update failed" error="failed to merge Pull Request https://github.com/my-org/my-repo/pull/3: failed to wait until Pull Request https://github.com/my-org/my-repo/pull/3 is mergeable: failed to retrieve combined status of Pull Request https://github.com/my-org/my-repo/pull/3 for ref 0e5f7f8ce0e2372dbf53ce955223e8ac2e5c4b73: GET https://api.github.com/repos/my-org/my-repo/commits/0e5f7f8ce0e2372dbf53ce955223e8ac2e5c4b73/status: 403 Resource not accessible by integration []" repository=my-org/my-repo

[MPV]

But now when I've granted "repo admin view" permissions, I instead get this error (which I've yet to find the permission for):

failed to retrieve combined status of Pull Request https://github.com/my-org/my-repo/pull/3 for ref 0e5f7f8ce0e2372dbf53ce955223e8ac2e5c4b73: GET https://api.github.com/repos/my-org/my-repo/commits/0e5f7f8ce0e2372dbf53ce955223e8ac2e5c4b73/status: 403 Resource not accessible by integration []

I solved this one by granting Commit Statuses: Read. ✅

...as outlined here (I finally found those docs):

• https://docs.github.com/en/rest/overview/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-commit-statuses

[MPV]

So far the permissions I've granted are:

What	Permission	Comment
Administration	Read-only
Checks	Read-only
Commit statuses	Read-only
Contents	Read and write
Metadata (mandatory)	Read-only
Pull requests	Read and write
Workflows	Read and write	(as I'm making changes to such files)

[MPV]

...and now I'm at a place where it's failing with:

to merge Pull Request https://github.com/my-org/my-repo/pull/3: PUT https://api.github.com/repos/my-org/my-repo/pulls/3/merge: 405 Repository rule violations found\n\nAt least 1 approving review is required by reviewers with write access.\n\n []

...as seen in this excerpt:

time="2023-11-20T09:00:35Z" level=debug msg="Pull Request can be merged" pull-request="https://github.com/my-org/my-repo/pull/3" repository=my-org/my-repo
time="2023-11-20T09:00:37Z" level=error msg="Repository update failed" error="failed to merge Pull Request https://github.com/my-org/my-repo/pull/3: failed to merge Pull Request https://github.com/my-org/my-repo/pull/3: PUT https://api.github.com/repos/my-org/my-repo/pulls/3/merge: 405 Repository rule violations found\n\nAt least 1 approving review is required by reviewers with write access.\n\n []" repository=my-org/my-repo

[vbehar]

thanks for the detailed report. Indeed we need to do a better job at documenting the repository settings.
for your last issue (required review), we could also add an extra option to auto-approve the PR, although again depending on the repository settings this might or might not work.
I'll also have a look at github API to see if we can enable auto-merging by github when everything is OK

[MPV]

for your last issue (required review), we could also add an extra option to auto-approve the PR, although again depending on the repository settings this might or might not work.

I'll also have a look at github API to see if we can enable auto-merging by github when everything is OK

That's amazing ideas! 😍

[navin-oss]

I’d like to work on this issue.
I can document the required GitHub App / PAT permissions for --pr-merge, including common failure cases and repository rules.

[vbehar]

thanks, that would be nice!

[navin-oss]

I’ve added documentation clarifying the required GitHub App / PAT permissions for --pr-merge.

This is covered in PR #415, including branch protection and status check access.
Happy to refine if anything should be adjusted.