Skip to content

Importing a GitHub repository to GerritHub

Jump to bottom
Paul Jolly edited this page Nov 27, 2024 · 3 revisions

This wiki contains some rough notes on how to import an existing GitHub repository to GerritHub.

To help the explanation that follows, we will use an example:

  • the repository we are importing is cue-lang/cue;
  • the bot account (see blow) has a GitHub username of cueckoo.

This guide also assumes that you have git-codereview installed and are familiar with using it and Gerrit.

Gerrit configuration

It is worth thinking well ahead of time how you want to configure Gerrit. This is beyond the scope of this wiki, but here are some points you will want to consider:

  • What merge strategy do you want? We use cherry-pick.
  • Do you want to limit the creation of branches on GerritHub? We lock down branch creation to a special super-admin bot account on the basis this is a rare occurrence.
  • Do you want to limit the creation of tags on GerritHub? Like branch creation, we lock down tag creation to a special super-admin bot account. Creating a tag almost always creates a release for Go projects, so this should be done with care (ideally we will put some tooling around this where the tag creation requires approval).
  • What labels do you want for CLs? We have the standard Code-Review, and use the Trybot-Result to indicate the result of CI runs.
  • Who do you want to be able to view your configuration? We lock down our configuration to admins. In the future, this will allow us to configure webhooks for Gerrit events.
  • What requirements do you want to place on CLs prior to submission? We required a Code-Review=+2, no holds (approvers can mark a CL Hold=+1 to prevent submission), TryBot-Result=+1, no DO NOT SUBMIT and no DO NOT REVIEW.
  • Do you want to required each commit to be signed off? We do, as this asserts the developer certificate of origin.
  • What Gerrit groups will you need to enable the points above?

One point that follows from the above in the context of GerritHub. By default, GerritHub replicates refs/meta/config to GitHub. This is something of a security problem to our mind because it subverts any access controls you might put on this special ref. We have raised an issue for discussion, but for now you can request to not have refs/meta/config mirrored to GitHub.

You can (and should) create the configuration and group structure you require ahead of time. Trying to do this on-the-fly later will result in pain!

Pre import preparation

  • Create a bot account. You will use this bot account for the initial import to GerritHub, but it will also be used to authenticate the mirror from GerritHub to GitHub. The bot account will require write access to the repository you want to import, and will also need to be a member of the organisation that contains the repository. Follow these steps:
    • Create new Gmail account;
    • Create a new GitHub account using the Gmail address;
    • Authorise GerritHub for the bot user, choosing the Workflow scope;
    • Set the name of the bot user in GerritHub via Settings.
  • Create .github/CODEOWNERS in the GitHub repository with just the bot account listed. This will prevent accidental merges of Pull Requests in the GitHub repository once you have completed the import to GerritHub.
* @cueckoo

Import repository into GerritHub

** This step should be performed as the bot user you created earlier. **

Use the GerritHub wizard to perform the import.

Ensure that the HEAD pointer (which defines the default branch) is correct. Continuing as the bot user, visit the branches page for your repository (adjusting the path for your repository). In the Revision column for the HEAD row, you will see an EDIT link which allows you to define the branch name of the default branch. If your GitHub repository default branch name is not master then you might run into this bug.

Post import configuration

At this point, the bot user is the only user configured to do anything with the resulting GerritHub repository. The first step therefore is to alter the configuration to use the Gerrit groups you created earlier.

As the bot user, clone (via https with a .netrc for auth?) the config branch and update per unity (CUE repo has unity config):

cd $(mktemp -d)
export HOME=$PWD
cat <<EOD > .netrc
machine review.gerrithub.io
login cueckoo
password ******
EOD
git clone "https://cueckoo@review.gerrithub.io/a/cue-lang/cue"
cd cue
git fetch origin refs/meta/config:refs/remotes/origin/refs/meta/config
git switch -c initial_config_change origin/refs/meta/config

Make the relevant changes to project.config and groups, and add a copy of the codereview.cfg file to help git-codereview understand which Gerrit instance you are talking to for config changes. Then commit and mail as you would for any normal Gerrit CL. Note that you will have to self-CodeReview+2 this change as the bot user because nobody else is, at this stage, configured to be a part of the project. Once the config change is submitted, you should then be able to mail and submit (config) changes according to the permissions/groups you established.

At this point you will also want to contact GerritHub to request that they:

  • Configure force-push for refs/heads/**, refs/tags/**, refs/changes/*.
  • Do not mirror refs/meta/config.

Helping your contributors adapt to the change

The CUE project has pulled together a couple of wikis

The CUE project uses github.com/cue-lang/contrib-tools/cmd/cueckoo as a CLI convenience tool for:

  • Triggering the trybots for a GerritHub-based repository.
  • Importing Pull Requests from GitHub.

Gerrit(Hub) issues

Here is a list of relevant Gerrit(Hub) issues:

Clone this wiki locally