| commit | 87a8a38e62c43dddeca150a8a2e5b400250032d7 | [log] [tgz] |
|---|---|---|
| author | Luca Milanesio <luca.milanesio@gmail.com> | Tue Jun 18 00:15:48 2024 +0100 |
| committer | Luca Milanesio <luca.milanesio@gmail.com> | Wed Jun 19 12:40:56 2024 +0100 |
| tree | 9e8b67b14ffcf136cc4ef427d3bb7ef6247dc8b2 | |
| parent | 06bcc598095c83414def92911dc1f27f6a32dcbf [diff] |
Introduce default github build target All plugins are expected to have a main build target having the same name as the plugin's directory. Introduce the 'github' plugin which is the main node of the dependency of all other targets, including the one responsible for extracting the plugin's version into a version file. Change-Id: I9fb3694e5fb2c4cbf0455d54281ee2677429d16f
This plugin allows existing GitHub repositories to be integrated as Gerrit projects.
Many people see Gerrit and GitHub as opposites: the pull-request model adopted by GitHub is often used as “easy shortcut” to the more comprehensive and structured code-review process in Gerrit.
There are many discussion threads on this:
In reality there are already OpenSource projects that have started using the two tools together:
The reason for using GitHub and Gerrit together are: a) GitHub is widely recognised and accessible by lots of world-wide sites. b) Using a public GitHub repo allows to “off-load” a lot of git pull traffic. c) Pull-request allows novice users to start getting involved. d) Gerrit code-review define the quality gates for avoiding “noise” of unstructured contributions.
When using GitHub and Gerrit together, the “master of truth” has to be Gerrit: this is because it is the place where more control in terms of security and workflow can be defined.
A Gerrit plugin can help controlling the GitHub replica and importing the pull requests as Gerrit changes.
Users can login to Gerrit using the same username and credentials in GitHub. Gerrit login points to GitHub for generating the OAuth token to be used for the code-review authenticated session.
The initial Gerrit registration page can be customised to import GitHub SSH Keys directly into Gerrit.
Existing GitHub repositories are automatically replicated to Gerrit for the purpose of performing code-review and pushing back changes once approved. Additionally to the standard Gerrit push replication, supports as well the ability to pull branches from remote GitHub repositories.
Hooks into the GitHub pull-request mechanism to automatically create a Change in Gerrit submitted for review.
GitHub plugin is designed to work with Gerrit 3.3 (currently in development). In order to build the GitHub plugin you need to have a working Gerrit 3.3 build in place.
See https://gerrit-review.googlesource.com/Documentation/dev-bazel.html for a reference on how to build Gerrit using Bazel.
Gerrit 3.3 is distributed for Java 11 only. However, the source code is compatible with Java 8 assuming you build it from the source repository by yourself.
The GitHub plugin can be built for Java 17 by using the javaVersion=1.17 Maven parameter.
Example: git clone https://gerrit.googlesource.com/plugins/github cd github mvn -DjavaVersion=17 install
You need to install the singleusergroup plugin for Gerrit (see https://gerrit-review.googlesource.com/#/admin/projects/plugins/singleusergroup).
This plugin is needed to allow Gerrit to use individual users as Groups for being used in Gerrit ACLs. As of Gerrit 3.3 singleuserplugin is a core plugin and included in Gerrit tree (if it was cloned recursively).
Example: cd gerrit bazelisk build plugins/singleusergroup cp bazel-bin/plugins/singleusergroup/singleusergroup.jar $GERRIT_SITE/plugins/.
Just clone the Git repository (see https://gerrit-review.googlesource.com/#/admin/projects/plugins/github) and do a mvn install from the root directory. This will create two JARs under github-oauth/target and github-plugin/target: the oauth is a JAR library to be copied to $GERRIT_SITE/lib whilst the plugin JAR has to be installed as usual under $GERRIT_SITE/plugins.
Example: git clone https://gerrit.googlesource.com/plugins/github cd github mvn install cp github-oauth/target/github-oauth-.jar $GERRIT_SITE/lib cp github-plugin/target/github-plugin-.jar $GERRIT_SITE/plugins
Note: Client ID & Client Secret are generated that used in the next step.
java -jar bazel-bin/gerrit.war init -d $GERRIT_SITE
User Authentication
Authentication method []: HTTP
Get username from custom HTTP header [Y/n]? Y
Username HTTP header []: GITHUB_USER
SSO logout URL : /oauth/reset
GitHub Integration
GitHub URL: [https://github.com]:
GitHub API URL: [https://api.github.com]:
ClientId []:
ClientSecret []:
Gerrit OAuth implementation [http/?]:
etc/gerrit.config and etc/secure.config files in your $gerrit_site.webhookUser entry in github section of etc/gerrit.configwebhookSecret entry in github section of etc/secure.config.The GitHub plugin uses the lombok library, which provides a set of annotations to reduce the amount of boilerplate code that has to be written.
To build the plugin in Eclipse, the Lombok Eclipse integration must be installed.
Download lombok.jar from http://projectlombok.org/ and install:
java -jar lombok.jar
Follow the instructions to select your Eclipse installation if the installer cannot detect it automatically.
After the installation, Eclipse must be restarted and compilation errors should disappear.
Before importing a repository from github, this plugin checks that its git refs do not clash with Gerrit magic refs, since importing those refs would prevent users from creating change requests.
Attempting to import repositories having refs starting with refs/for/ or refs/meta will fail with an error message. For example:
Found 2 ref(s): Please remove or rename the following refs and try again: refs/for/foo, refs/meta/bar
More information on Gerrit magic refs can be found here