Add MAINTAIN and TRIAGE permissions

[MarkEWaite]

Add MAINTAIN and TRIAGE permissions to permission type

• Shows GHRepository#getPermission fails with a user having the maintain role #1671 Create a test demoing the issue
• Fixes GHRepository#getPermission fails with a user having the maintain role #1671 by adding MAINTAIN and TRIAGE permissions to permission type

I've not included links to the GitHub REST API documentation describing those pemrissions because I've been unable to find them listed in the REST API documentation. I'm confident that they are in the documentation, but my search and navigation skills are insufficient to find them.

Failures for MAINTAIN permission on ci.jenkins.io are documented in:

• ci.jenkins.io repository scan of jenkins.io repo fails with a stack trace jenkins-infra/helpdesk#3617

Failures for TRIAGE permission on other systems are documented in:

• Community post - Multibranch pipline fails because TRIAGE enum doesn't exist

Special thanks to @PierreBietz for his investigation work and the test case that shows the issue.

Requesting review from @jglick and @basil in case I've missed something important in the implementation.

Before submitting a PR:

• Changes must not break binary backwards compatibility. If you are unclear on how to make the change you think is needed while maintaining backward compatibility, CONTRIBUTING.md for details.
• Add JavaDocs and other comments explaining the behavior.
• When adding or updating methods that fetch entities, add @link JavaDoc entries to the relevant documentation on https://docs.github.com/en/rest .
• Add tests that cover any added or changed code. This generally requires capturing snapshot test data. See CONTRIBUTING.md for details.
• Run mvn -D enable-ci clean install site locally. If this command doesn't succeed, your change will not pass CI.
• Push your changes to a branch other than main. You will create your PR from that branch.

When creating a PR:

• Fill in the "Description" above with clear summary of the changes. This includes:
  • If this PR fixes one or more issues, include "Fixes #" lines for each issue.
  • Provide links to relevant documentation on https://docs.github.com/en/rest where possible. If not including links, explain why not.
• All lines of new code should be covered by tests as reported by code coverage. Any lines that are not covered must have PR comments explaining why they cannot be covered. For example, "Reaching this particular exception is hard and is not a particular common scenario."
• Enable "Allow edits from maintainers".

[codecov]

Codecov Report

Patch coverage: 100.00% and no project coverage change.

Comparison is base (7403e25) 79.93% compared to head (49a93bf) 79.93%.

❗ Current head 49a93bf differs from pull request most recent head ff16417. Consider uploading reports for the commit ff16417 to get more accurate results

Additional details and impacted files

@@            Coverage Diff            @@
##               main    #1672   +/-   ##
=========================================
  Coverage     79.93%   79.93%           
  Complexity     2208     2208           
=========================================
  Files           212      212           
  Lines          6687     6689    +2     
  Branches        364      364           
=========================================
+ Hits           5345     5347    +2     
  Misses         1128     1128           
  Partials        214      214           

Impacted Files	Coverage Δ
...main/java/org/kohsuke/github/GHPermissionType.java	100.00% <100.00%> (ø)

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[jglick]

As in #1671 (comment) I would suggest adding an UNKNOWN or OTHER constant and making GHPermission.getPermissionType fall back to that.

I do not believe any change to github-branch-source is required since https://github.com/jenkinsci/github-branch-source-plugin/blob/d391eef681ae51743402ef08deac2b94565b09aa/src/main/java/org/jenkinsci/plugins/github_branch_source/ForkPullRequestDiscoveryTrait.java#L319-L325 only cares about ADMIN and WRITE. You should of course push a release of https://plugins.jenkins.io/github-api/.

[car-roll]

@bitwiseman Looks like I don't have release permissions. would you be able to cut a release for this issue? many thanks!

[jglick]

Better hold off until we have analyzed the impact of the GitHub.com rollback.

[MarkEWaite]

Better hold off until we have analyzed the impact of the GitHub.com rollback.

As far as I can tell, the new entries in the enumeration do not harm the plugin even after the GitHub REST API rollback. The rollback has happened and scan repository is working as expected with the patched github API library.

GitHub announced maintain and triage in a 2019 blog post, but uses the word roles to describe them rather than calling them permissions. I'm not sure if that means that maintain and triage do not belong in the GHPermissionType enumeration or if they belong there.

I'm OK if we roll back this change and hope that GitHub won't make this type of change in the future, or we could partially revert it so that we don't add maintain or triage to the enumeration but would not throw an exception if values were added to the enumeration