Add documentation for GITHUB_TOKEN requirement

[Mathieu Malaterre]

The documentation does not make it very clear what type of access is required:

1. fine-grained personal access token ?
2. personal access token (classic) ?

What type of permissions ?

Thanks

[Brendan]

This is mainly because it was unclear from the REST API docs what exact permission it needed to execute.

You are correct though. We should mention explicitly what permissions are used when the token is required.

[Brendan]

Just so you can see what vagueness I'm working with:

1. REST API list of endpoints for commits and issues which is used for PR threads also. The pulls endpoints are about PR reviews (when it concerns comments) which are much more complex to implement, so we hardly use the pulls endpoints.
2. We use the following REST API when tokens are needed:
   • For a PR:
     • GET /repos/{owner}/{repo}/issues/{issue_number}/comments (needed for fetching existing comments)
     • DELETE /repos/{owner}/{repo}/issues/comments/{comment_id} (used to delete comments that this action creates)
     • POST /repos/{owner}/{repo}/issues/{issue_number}/comments (used to create a new thread comment)
     • GET /repos/{owner}/{repo}/pulls/{pull_number} to get list of changed files
   • For a commit (push event):
     • GET /repos/{owner}/{repo}/commits/{commit_sha}/comments (needed for fetching existing comments)
     • DELETE /repos/{owner}/{repo}/comments/{comment_id} (used to delete comments that this action creates)
     • POST /repos/{owner}/{repo}/commits/{commit_sha}/comments (used to create a new thread comment)
     • GET /repos/{owner}/{repo}/commits/{ref} to get list of changed files

[Brendan]

1. fine-grained personal access token ?

This feature is still in beta and lacks adequate documentation to answer the question. While it might work with this action, we won't be held responsible if it doesn't.

---

From what I can gather, I think the following permissions are used when a token is required (for a public repo). Note, this is mostly guesses since the REST API doesn't always mention for what the token needs permission.

permissions:
  checks: read|write
  # write for our file-annotations option (I think - probably not)

  pull-requests: read|write 
  # write to remove duplicate action comments and post new comments
  # read to get a list of changed files and a list of existing comments

  repository-projects: read|write  # (for push events)
  # write to remove duplicate action comments and post new comments
  # read to get list of changed files and a list of existing comments

See also Assigning permissions to jobs.

Private repo access seems largely undocumented, but we have [reportedly] run into permission problems when getting a list of PR comments and a list of changed files.

---

I think the only way we can be certain what permissions are needed is by trial and error (we have a test repo for that). But my time is currently limited, and I would very much appreciate user feedback on what permission settings worked and what didn't.

[Mathieu Malaterre]

Could also comment, why at least one alternative solution works out of the box (no need for GITHUB_TOKEN setup):

• https://github.com/marketplace/actions/clang-tidy-review#inputs

Example:

• malaterre/libdicm#50 (comment)

AFAIK all read operations are supported, the only missing one is the writting on pull pages. Which for some reason is supported by default with ZedThree/clang-tidy-review.