Update github-app.adoc

[Rad710]

Hi. I had to also grant Checks: Read and Write permission to the GitHub App for the plugin to work. I believe the documentation should be updated to add this

Description

A brief summary describing the changes in this pull request. See
JENKINS-XXXXX for further information.

Submitter checklist

• Link to JIRA ticket in description, if appropriate.
• Change is code complete and matches issue description
• Automated tests have been added to exercise the changes
• Reviewer's manual test instructions provided in PR description. See Reviewer's first task below.

Reviewer checklist

• Run the changes and verify that the change matches the issue description
• Reviewed the code
• Verified that the appropriate tests have been written or valid explanation given

Documentation changes

• Link to jenkins.io PR, or an explanation for why no doc changes are needed

Users/aliases to notify

[olamy]

we might need something to read org members as well.

[jglick]

Why?

[olamy]

because of this usage

github-branch-source-plugin/src/main/java/org/jenkinsci/plugins/github_branch_source/GitHubSCMSource.java

Line 1576 in 6bfb8df

return collaboratorNames = new HashSet<>(ghRepository.getCollaboratorNames());

And causing scan failure:

org.kohsuke.github.HttpException: {"message":"Resource not accessible by integration","documentation_url":"https://docs.github.com/rest/collaborators/collaborators#list-repository-collaborators"}
	at org.kohsuke.github.GitHubConnectorResponseErrorHandler$1.onError(GitHubConnectorResponseErrorHandler.java:62)
	at org.kohsuke.github.GitHubClient.detectKnownErrors(GitHubClient.java:473)
	at org.kohsuke.github.GitHubClient.sendRequest(GitHubClient.java:434)
	at org.kohsuke.github.GitHubPageIterator.fetch(GitHubPageIterator.java:146)
	at org.kohsuke.github.GitHubPageIterator.hasNext(GitHubPageIterator.java:93)
	at org.kohsuke.github.PagedIterator.fetch(PagedIterator.java:116)
	at org.kohsuke.github.PagedIterator.nextPageArray(PagedIterator.java:144)
	at org.kohsuke.github.PagedIterable.toArray(PagedIterable.java:79)
	at org.kohsuke.github.PagedIterable.toArray(PagedIterable.java:107)
	at org.kohsuke.github.GHRepository.getCollaboratorNames(GHRepository.java:1039)
	at org.jenkinsci.plugins.github_branch_source.GitHubSCMSource.updateCollaboratorNames(GitHubSCMSource.java:1576)
	at org.jenkinsci.plugins.github_branch_source.GitHubSCMSource$LazyContributorNames.create(GitHubSCMSource.java:2833)
	at org.jenkinsci.plugins.github_branch_source.LazySet.delegate(LazySet.java:59)
	at org.jenkinsci.plugins.github_branch_source.LazySet.contains(LazySet.java:79)
	at org.jenkinsci.plugins.github_branch_source.ForkPullRequestDiscoveryTrait$TrustContributors.checkTrusted(ForkPullRequestDiscoveryTrait.java:283)
	at org.jenkinsci.plugins.github_branch_source.ForkPullRequestDiscoveryTrait$TrustContributors.checkTrusted(ForkPullRequestDiscoveryTrait.java:273)
	at jenkins.scm.api.trait.SCMHeadAuthority.isTrusted(SCMHeadAuthority.java:101)
	at jenkins.scm.api.trait.SCMSourceRequest.isTrusted(SCMSourceRequest.java:213)
	at org.jenkinsci.plugins.github_branch_source.GitHubSCMSource$4.create(GitHubSCMSource.java:1254)
	at org.jenkinsci.plugins.github_branch_source.GitHubSCMSource$4.create(GitHubSCMSource.java:1248)
	at jenkins.scm.api.trait.SCMSourceRequest.process(SCMSourceRequest.java:339)
	at org.jenkinsci.plugins.github_branch_source.GitHubSCMSource.retrievePullRequest(GitHubSCMSource.java:1245)
	at org.jenkinsci.plugins.github_branch_source.GitHubSCMSource.retrieve(GitHubSCMSource.java:1085)
	at jenkins.scm.api.SCMSource._retrieve(SCMSource.java:372)
	at jenkins.scm.api.SCMSource.fetch(SCMSource.java:282)
	at jenkins.branch.MultiBranchProject.computeChildren(MultiBranchProject.java:654)
	at com.cloudbees.hudson.plugins.folder.computed.ComputedFolder.updateChildren(ComputedFolder.java:269)
	at com.cloudbees.hudson.plugins.folder.computed.FolderComputation.run(FolderComputation.java:167)
	at jenkins.branch.MultiBranchProject$BranchIndexing.run(MultiBranchProject.java:1057)
	at hudson.model.ResourceController.execute(ResourceController.java:101)
	at hudson.model.Executor.run(Executor.java:442)
Finished: FAILURE

[jglick]

Huh, had not seen that in the past. Clearly only applies in certain circumstances (PRs being filed from forks, and this trust setting used).

[jglick]

As written, this is misleading. jenkinsci/github-checks-plugin#321 is actually the correct documentation: if you want to use github-checks then you would need this permission. So mentioning the permission here is fine so long as it is clarified that this plugin would not actually use it.

Note that CloudBees CI users also have a different plugin offering Checks integration that works with github-branch-source but this has its own App creation wizard which defines appropriate permissions automatically: https://docs.cloudbees.com/docs/cloudbees-ci/latest/scm-integration/enabling-scm-reporting#_enabling_github_app_authentication

[jglick]

Why?