Impacted version: 4.33.0

Deployment mode:
Not a gitbucket user, but hub4j/github-api library maintainer which users of gitbucket depend on.

Problem Description

What version of the GitHub REST API does GitBucket currently implement?

The answer to that question is currently either undefined or "whatever api.github.com does" (which is nearly the same thing). The api.github.com REST API is documented, but it is also continually changing. Those changes are mostly non-breaking additions, but also include other changes and removals on a rolling day-by-day basis.

This means that on any given day the behavior of api.github.com may change in a way to forces GitBucket to take some equivalent high-priority fix to match it. Without this the GitBucket API will continually be trying and failing to match the current behavior of api.github.com. This is a recipe for user confusion and developer burn out.

Suggested fix

Target one specific version of the GitHub REST API

While the api.github.com REST API may change at any time, the GitHub Enterprise REST API does not. Each release of GitHub Enterprise has a known REST API that will only include bug fix changes.

GitBucket should select a specific version of the GitHub REST API to implement. This would allow GitBucket to target a known stable API. The GitBucket team could make changes and move to target new versions on a planned schedule, largely independent of GitHub. Further, when users file issues there will be a stable rubric against which the behavior of GitBucket can be measured.

I suggest starting with GitHub Enterprise v21, just because it is the latest version at the time of this writing.

Implement Meta API with installed_version field

GitHub REST API provides a /meta endpoint which provides useful information about the service. The GitHub Enterprise /meta endpoint includes the installed_version field letting consumers of the API detect what version of the service they are interacting with.

GitBucket should implement the /meta endpoint and return a installed_version field value matching the current target GitHub Enterprise REST API version. This would make it allow other tools interacting with the GitBucket to match their behavior to the expected GitBucket behavior. Libraries such as hub4j/github-api (#2437, #2459) and tools such as GitHub Desktop (#1565) could reasonably be expected to work with GitBucket depending on how accurately GitBucket matched the behavior of the target version of the GitHub Enterprise REST API.