Setting Up Your Gerrit Account¶

Note

This section assumes you have completed Setup and Learn GIT guide.

What is Gerrit?¶

This is the review system the OpenStack community uses.

Gerrit allows you to review:

Sign Up¶

Visit OpenStack’s Gerrit page and click the sign in link.
You will be prompted to select a username. You can enter the same one you did for Launchpad, or something else.

Note

Choose and type your username carefully. Once it is set, you cannot change the username.

Note

From here on out when you sign into Gerrit, you’ll be prompted to enter your Launchpad login info. This is because Gerrit uses it as an OpenID single sign on.

Individual Contributor Licence Agreement (ICLA)¶

What is it?¶

An agreement to clarify intellectual property rights granted with contributions from a person or entity. Preview the full agreement.

Signing it¶

Individual Contributors¶

In Gerrit’s settings click the New Contributor Agreement link and sign the agreement. You need this to contribute code & documentation. You will not be able to push patches to Gerrit without this.

Contributors From a Company or Organisation¶

If you are contributing on behalf of a company or organization, please make sure that you sign the ICLA AND also get added to the list of contributors on your company’s Corporate Contributor Licence Agreement (CCLA). You will need to complete both of these steps before being able to contribute.

In Gerrit’s settings click the New Contributor Agreement link and sign the agreement.
An employer with the appropriate signing rights of the company or organization needs to sign the Corporate Contributor Licence Agreement.
If the CCLA only needs to be extended follow this procedure.

Note

Employers can update the list of authorized employees by filling out and signing an Updated Schedule A Form.

Contributors From the U.S. Government¶

Someone of authority needs to sign the U.S. Government Contributor License Agreement. Contact the Open Infrastructure Foundation to initiate this process.

Setup SSH Keys¶

What are they?¶

In order to push things to Gerrit we need to have a way to identify ourselves. We will do this using SSH keys which allows us to have our machine we’re pushing a change from to perform a challenge-response authentication with the Gerrit server.

SSH keys are always generated in pairs:

Private key - Only known to you and it should be safely guarded.
Public key - Can be shared freely with any SSH server you wish to connect to.

In summary, you will be generating a SSH key pair, and providing the Gerrit server with your public key. With your system holding the private key, it will have no problem replying to Gerrit during the challenge-response authentication.

Some people choose to use one SSH key pair to access many systems while others prefer to use separate key pairs. Both options are covered in the following sections.

Check For Existing Keys¶

Open your terminal program and type:

ls -la ~/.ssh

Typically public key filenames will look like:

id_dsa.pub
id_ecdsa.pub
id_ed25519.pub
id_rsa.pub

If you don’t see .pub extension file or want to generate a specific set for OpenStack Gerrit, you need to generate keys.

Generate SSH Key Pairs¶

Note

This guide recommends using ed25519 keys because it has been found that this type works well across all operating systems.

Generating The Default Or Initial SSH Key Pair¶

You can generate a new SSH key pair using the provided email as a label by going into your terminal program and typing:

ssh-keygen -t ed25519 -C "your_email@example.com"

When you’re prompted to “Enter a file in which to save the key” press Enter. This accepts the default location:

Enter a file in which to save the key (/Users/you/.ssh/id_ed25519): [Press enter]

At the prompt, type a secure passphrase, you may enter one or press Enter to have no passphrase:

Enter passphrase (empty for no passphrase): [Type a passphrase]
Enter same passphrase again: [Type passphrase again]

Generating A Separate Key Pair For OpenStack Gerrit (optional)¶

You can generate a new SSH key using the provided email as a label by going into your terminal program and typing:

ssh-keygen -t ed25519 -C "your_email@example.com"

When you’re prompted to “Enter a file in which to save the key” you must specify the name of the new key pair and then press Enter:

Enter a file in which to save the key (/Users/you/.ssh/id_ed25519): /Users/you/.ssh/id_openstack_ed25519

At the prompt, type a secure passphrase, you may enter one or press Enter to have no passphrase:

Enter passphrase (empty for no passphrase): [Type a passphrase]
Enter same passphrase again: [Type passphrase again]

Finally you need to tell ssh what host(s) to associate SSH keys with. To do this open “~/.ssh/config” in an editor, create the file if it doesn’t exist and add something like:

Host review.opendev.org review
  Hostname review.opendev.org
  Port 29418
  User <your_gerrit_username>
  IdentityFile ~/.ssh/id_openstack_ed25519

Copy Public Key¶

Mac OS & Linux¶

From your terminal type:

cat ~/.ssh/id_ed25519.pub

Or if you created a separate key pair, assuming the example name above:

cat ~/.ssh/id_openstack_ed25519.pub

Select and copy the output.

Import Public Key Into Gerrit¶

Go to Gerrit’s SSH Keys section in User Settings.
Paste the public key into the New SSH Key text box.
Click the ‘ADD NEW SSH KEY’ button.

Git Review¶

What is it?¶

Git review is a tool maintained by the OpenStack community. It adds an additional sub-command to ‘git’ like so:

git review

When you have changes in an OpenStack project repository, you can use this sub-command to have the changes posted to Gerrit so that they can be reviewed.

Installation¶

Mac OS¶

In a terminal type:

pip install git-review

If you don’t have pip installed already, follow the installation documentation for pip.

Note

Mac OS X El Capitan and Mac OS Sierra users might see an error message like “Operation not permitted” when installing with the command. In this case, there are two options to successfully install git-review.

Option 1: install using pip with more options:

pip install --install-option '--install-data=/usr/local' git-review

Option 2: Use the package manager Homebrew, and type in a terminal:

brew install git-review

Linux¶

For distributions like Debian, Ubuntu, or Mint open a terminal and type:

sudo apt install git-review

For distributions like RedHat, Fedora or CentOS open a terminal and type:

sudo dnf install git-review

For SUSE distributions open a terminal and type:

sudo zypper in python-git-review

Configuration¶

Git review assumes the user you’re running it as is the same as your Gerrit username. If it’s not, you can tell it by setting this git config setting:

git config --global gitreview.username <username>

If you don’t know what your Gerrit username is, you can check the Gerrit settings.

Preparing to Send a Review¶

Before doing git commit on your patch it is important to initialize git review. Use the following command to do the initial git review configuration in your repository:

git review -s

The command sets up the necessary remote hosts and commit hooks to enable pushing changes to Gerrit.

Note

Git review only needs to be initialised once in a repository.

Setting Up Your Gerrit Account

Setting Up Your Gerrit Account¶

What is Gerrit?¶

Individual Contributor Licence Agreement (ICLA)¶

What is it?¶

Signing it¶

Individual Contributors¶

Contributors From a Company or Organisation¶

Contributors From the U.S. Government¶

Setup SSH Keys¶

What are they?¶

Check For Existing Keys¶

Generate SSH Key Pairs¶

Generating The Default Or Initial SSH Key Pair¶

Generating A Separate Key Pair For OpenStack Gerrit (optional)¶

Copy Public Key¶

Mac OS & Linux¶

Import Public Key Into Gerrit¶

Git Review¶

What is it?¶

Installation¶

Mac OS¶

Linux¶

Configuration¶

Preparing to Send a Review¶

contributor-guide

Page Contents