From: Jessica Wagantall Date: Wed, 25 Oct 2017 17:50:35 +0000 (-0700) Subject: Add Gerrit documentation (How to clone) X-Git-Url: https://gerrit.linuxfoundation.org/infra/gitweb?a=commitdiff_plain;h=refs%2Fchanges%2F69%2F7069%2F21;p=releng%2Fdocs.git Add Gerrit documentation (How to clone) Topics include: - How to clone the code - Clone via SSH - Clone via anonymous HTTP - Clone via HTTP - Clone with commit-msg hook - Setting up Gerrit - Generating SSH keys for your system - Registering your SSH key with Gerrit Issue-ID: RELENG-556 Change-Id: I95ab738908f9e7c6a0dab43629f2d187b2a67c8b Signed-off-by: Jessica Wagantall --- diff --git a/docs/_static/gerrit-settings.png b/docs/_static/gerrit-settings.png new file mode 100644 index 0000000..a7217a4 Binary files /dev/null and b/docs/_static/gerrit-settings.png differ diff --git a/docs/_static/gerrit-sign-in.png b/docs/_static/gerrit-sign-in.png new file mode 100644 index 0000000..c28a531 Binary files /dev/null and b/docs/_static/gerrit-sign-in.png differ diff --git a/docs/_static/gerrit-ssh-keys.png b/docs/_static/gerrit-ssh-keys.png new file mode 100644 index 0000000..b714e73 Binary files /dev/null and b/docs/_static/gerrit-ssh-keys.png differ diff --git a/docs/gerrit.rst b/docs/gerrit.rst new file mode 100644 index 0000000..6671d3e --- /dev/null +++ b/docs/gerrit.rst @@ -0,0 +1,200 @@ +.. _lfreleng-docs-gerrit: + +############ +Gerrit Guide +############ + +Gerrit is an opensource web-based collaborative code review tool that +integrates with Git. Gerrit provides a framework for reviewing code commits +before it merges into the code base. +The changes are not made a part of the project until a code review completes. +Gerrit is also a good collaboration tool for storing the conversations that +occur around the code commits. + +.. note:: + + Here's more information on `Gerrit `_ + +How to clone code +================= + +Cloning the code into a local workspace can happen via HTTP or SSH. +Make sure your Gerrit settings are up to date with correct SSH and GPG keys. + +In the project's Gerrit instance, we can see the HTTP and SSH commands for +cloning any particular repo after browsing for a project. From the left side +menu, select Projects->List->Select any project or use the filter->General. + +SSH Clone +--------- + +This option provides a more secure connection. We should always use SSH for +pushing code unless the user is under a network that prevents SSH usage. +In such case, use HTTPS. + +.. note:: + + For more information on how to generate the public/private key pair see + `Generating SSH keys for your system`_ and `Registering your SSH key with Gerrit`_ + +.. note:: + + The SSH clone option will not appear if the settings are not updated with + the correct SSH keys. + +For example: + +.. code-block:: bash + + git clone ssh://jwagantall@gerrit.onap.org:29418/aaf/inno + +Since we are constantly working on uploading new code into the repositories, it's +recommended to use SSH clones since the remotes for pushing code get configured +appropriately. + +Anonymous HTTP Clone +---------------- + +Recommended if the intention is to view code and not make any contributions: +For example: + +.. code-block:: bash + + git clone https://gerrit.linuxfoundation.org/releng/docs + +Authenticated HTTP Clone +---------- + +This works everywhere, even behind a proxy or a firewall. +For example: + +.. code-block:: bash + + git clone https://USERNAME@gerrit.onap.org/r/a/aaf/inno + +This command will request a username and password. The username needs to match +the one set up in the Profile under Settings. Use the password from the Settings +under HTTP Password->Generate Password. + +.. note:: + + For Gerrit < 2.14 the HTTP password is not the same as the LFID password. + +.. note:: + + For Gerrit with HTTP configuration, the HTTP Password is in the User Name + (Top right corner) -> Settings -> HTTP Password -> Generate Password. + +Clone with commit-msg hook +-------------------------- + +Both SSH and HTTP clone options have a clone with commit-msg hook which adds +a hook for adding a new Change-Id as part of the footer of any new commit to +be able to post in Gerrit. + +This command is under Projects->List->Select any project or use the filter-> +General->Clone with commit-msg hook. + +The hook will edit any commit message adding a "Change-Id:" line in the footer. + +The hook implementation is intelligent at inserting the Change-Id line before +any Signed-off-by or Acked-by lines placed at the end of the commit message by +the author, but if no lines are present then it will insert a blank line, and +add the Change-Id at the bottom of the message. + +If a Change-Id line is already present in the message footer, the script will do +nothing, leaving the existing Change-Id unmodified. This permits amending an existing +commit, or allows the user to insert the Change-Id manually after copying it from +an existing change viewed on the web. + +To prevent the Change-Id addition, set gerrit.createChangeId to false in the +git config. + +Setting up Gerrit +================= + +Generating SSH keys for your system +----------------------------------- + +You must have SSH keys for your system to register with your Gerrit +account. The method for generating SSH keys is different for different +types of operating systems. + +The key you register with Gerrit must be identical to the one you will +use later to pull or edit the code. For example, if you have a +development VM which has a different UID login and keygen than that of +your laptop, the SSH key you generate for the VM is different from the +laptop. If you register the SSH key generated on your VM with Gerrit and +do not reuse it on your laptop when using Git on the laptop, the pull +fails. + +.. note:: + + Here's more information on `SSH keys for Ubuntu + `_ + and more on `generating SSH keys + `_ + +For a system running Ubuntu operating system, follow the steps below: + +#. Run the following command:: + + mkdir ~/.ssh + chmod 700 ~/.ssh + ssh-keygen -t rsa + +#. Save the keys, and add a passphrase for the keys. + + This passphrase protects your private key stored in the hard drive. + You must use the passphrase to use the keys every time you need + to login to a key-based system:: + + Generating public/private rsa key pair. + Enter file in which to save the key (/home/b/.ssh/id_rsa): + Enter passphrase (empty for no passphrase): + Enter same passphrase again: + +Your public key is now available as **.ssh/id\_rsa.pub** in your home +folder. + +Registering your SSH key with Gerrit +------------------------------------ + +#. Using a Google Chrome or Mozilla Firefox browser, go to + gerrit..org + +#. Click **Sign In** to access the repositories. + + .. figure:: _static/gerrit-sign-in.png + :alt: Sign into Gerrit + + Sign into Gerrit + +#. Click your name in the top right corner of the window and then click + **Settings**. + + The **Settings** page. + + .. figure:: _static/gerrit-settings.png + :alt: Settings page for your Gerrit account + + Settings page for your Gerrit account + +#. Click **SSH Public Keys** under **Settings**. + +#. Click **Add Key**. + +#. In the **Add SSH Public Key** text box, paste the contents of your + **id\_rsa.pub** file and then click **Add**. + + .. figure:: _static/gerrit-ssh-keys.png + :alt: Adding your SSH key + + Adding your SSH key + +To verify your SSH key, try using an SSH client to connect to Gerrit’s +SSHD port:: + + $ ssh -p 29418 @gerrit..org + Enter passphrase for key '/home/cisco/.ssh/id_rsa': + **** Welcome to Gerrit Code Review **** diff --git a/docs/index.rst b/docs/index.rst index d499ecd..e378491 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,6 +13,7 @@ Guides: :maxdepth: 2 best-practices + gerrit .. TODO Gerrit (RELENG-509) .. TODO Jenkins (RELENG-510)