############################## Setting Up Your Gerrit Account ############################## .. note:: This section assumes you have completed :doc:`git` guide. .. _what_is_gerrit: What is Gerrit? =============== This is the review system the OpenStack community uses. Gerrit allows you to review: * `Code, docs, infrastructure changes, and CI configurations `_ * `Specifications `_ * `Translations `_ * `Use cases for features `_ 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-license-agreement: Individual Contributor License 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. .. image:: /_assets/account-setup/3.png :scale: 70% :align: center Contributors From a Company or Organization ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 License 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. .. image:: /_assets/account-setup/3.png :scale: 70% :align: center #. An employer with the appropriate signing rights of the company or organization needs to sign the `Corporate Contributor License 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 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 Highlight 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 21 or earlier, or CentOS open a terminal and type:: sudo yum install git-review For Fedora 22 or later 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 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 reviews only needs to be initialized once in a repository.