Google Git
Sign in
gerrit / plugins / github / 9398c7877ab279303a29cb01120d681433d30a6b
commit9398c7877ab279303a29cb01120d681433d30a6b[log] [tgz]
authorAlvaro Vilaplana Garcia <alvaro.vilaplana@gmail.com>Wed Aug 30 10:35:50 2023 +0100
committerAlvaro Vilaplana Garcia <alvaro.vilaplana@gmail.com>Sat Sep 02 10:38:57 2023 +0100
treec0401941572172b603c50da58bc8d70466265550
parentb34da26abc259a239fe3828c6bf37ebb47016d8c [diff]
Build OAuth redirect URL when X-Forwarded-Host is present

In the past, when a Gerrit multi-site topology was used featuring a
primary domain, i.e example.com (serving as a geo-location load
balancer), along with multiple Gerrit sites like review-1.example.com
and review-2.example.com, the initiation of the GitHub sign-in flow
within any of the Gerrit sites triggered a redirection to GitHub,
referred to as the user's GitHub identity request [1]. During this
process, the redirect_uri query parameter was constructed using
information from the gerrit.canonicalWebUrl property defined in the
etc/gerrit.config file [2]. It's important to note that this property
occasionally contained a URL with a host matching the primary domain,
example.com. Consequently, when users attempted to sign in via GitHub,
they were redirected to this main domain.

However, with this updated approach, the redirect_uri is now constructed
based on the X-Forwarded-Host header if it is present in the request
(otherwise from gerrit.canonicalWebUrl). This means that when a sign-in
flow is initiated, for instance, from review-1.example.com, the
Forwarded-Host header will accurately contain the value
review-1.example.com. As a result, the redirection URL will utilize this
value as its host.

References:
[1] https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#web-application-flow
[2] https://gerrit-review.googlesource.com/Documentation/config-gerrit.html

Bug: Issue 297231231
Change-Id: I233824a202041c7a7d1905ef784ae2b6f8d23160
2 files changed
tree: c0401941572172b603c50da58bc8d70466265550
  1. github-oauth/
  2. github-plugin/
  3. .gitignore
  4. LICENSE
  5. pom.xml
  6. README.md
README.md

GitHub plugin

This plugin allows existing GitHub repositories to be integrated as Gerrit projects.

Why using GitHub and Gerrit together ?

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.

Why a Gerrit plugin ?

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.

Integration points

Authentication. (DONE - Change-Id: I7291a90014e51316af3cb07fd03785c1ef33acd0)

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.

Push-Pull replication. (DONE - Change-Id: I596b2e80b4d9519668a1ab289d6c950139d6a922)

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.

Pull-request to Change. (DONE - Change-Id: d669e351a03798cc2ec966d028458f083c232564)

Hooks into the GitHub pull-request mechanism to automatically create a Change in Gerrit submitted for review.

How to build this plugin

Gerrit 3.3 build

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 8 by using the javaVersion=1.8 Maven parameter.

Example: git clone https://gerrit.googlesource.com/plugins/github cd github mvn -DjavaVersion=1.8 install

singleusergroup plugin

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/.

Building GitHub integration for Gerrit

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

Register Gerrit as a Github OAuth application

Note: Client ID & Client Secret are generated that used in the next step.

Running Gerrit init to configure GitHub OAuth

  • 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]:

  • Use GitHub for Gerrit login? [Y/n] Y

  • ClientId []:

  • ClientSecret []:

Receiving Pull Request events to automatically import

  • Create a github user account which automatic import operation uses.
  • Register the account to your gerrit site by logging into Gerrit with the account.
  • Create webhook on your github repository.
    • The payload URL should be something like http://your-gerrit-host.example/plugins/github-plugin-version/webhook.
    • It is recommended to specify some webhook secret.
  • Edit etc/gerrit.config and etc/secure.config files in your $gerrit_site.
    • Add the github user account name as webhookUser entry in github section of etc/gerrit.config
    • Add the webhook secret as webhookSecret entry in github section of etc/secure.config.

Enhancing GitHub Sign-In Redirection in a Gerrit Multi-Site setup

To ensure the success of the “Sign in flow,” two critical aspects must be addressed:

  1. GitHub OAuth Application Registration: When registering Gerrit as a GitHub OAuth application, it is imperative that the property “Authorization callback URL” includes the primary domain as the host, i.e https://my-domain.org/oauth. This is essential to ensure that Gerrit sites like review-1.my-domain.org or review-2.my-domain.org are correctly redirected once authorization has been granted by GitHub. This requirement aligns with the documentation on redirect_uri:
The redirect_uri parameter is optional. If omitted, GitHub will redirect
users to the callback URL configured in the OAuth app settings. If
provided, the redirect URL's host (excluding sub-domains) and port must
exactly match the callback URL. The redirect URL's path must reference
a subdirectory of the callback URL.

For a callback URL like https://my-domain.org/oauth:

  • Valid redirect_uri examples:
1. https://my-domain.org/oauth
2. https://my-domain.org/oauth/subdir/other
3. https://review-1.my-domain.org/oauth
4. https://review-2.my-domain.org/oauth
5. https://review-1.my-domain.org/oauth/subdir/other
  • Invalid redirect_uri examples:
1. https://my-domain.org/bar
2. https://my-domain.org/
3. https://my-domain.org:8080/oauth
4. https://review-1.my-domain.org:8080/oauth
5. https://my-domain.com
  1. Propagation of the X-Forwarded-Host Header: It is essential to ensure the propagation from the upstream proxy of the header X-Forwarded-Host.

Contributing to the GitHub plugin

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.

Notes

Magic refs

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