Page tree
Skip to end of metadata
Go to start of metadata

Overview

Gerrit is an Open Source web-based collaborative Code Review tool that integrates with Git.
For all OPEN-O projects, Gerrit is available at https://gerrit.open-o.org and documentation at https://gerrit.open-o.org/r/Documentation/index.html 
Gerrit offers an extensive search capability by using a query syntax documented at https://gerrit.open-o.org/r/Documentation/user-search.html 
To get started, you can watch this 14 minutes video that was done for OPNFV project.

To understand deeper Gerrit UI, this is a good source of info https://gerrit-review.googlesource.com/Documentation/user-review-ui.html 
Log into Gerrit using your Linux Foundation ID (LFID).

Anyone who has a valid Linux Foundation ID can submit code as a contributor. You simply need to login into Gerrit using your Linux Foundation ID.
The committer role requires specific permissions per project setup by Linux Foundation. Do not contact directly Linux Foundation's Help Desk to ask for Committer privileges but rather work the Release Manager.

Project committers group are setup in the form of openo-gerrit-${PROJECT}-committers. Connect to https://identity.linuxfoundation.org to see which group you are part of.
Committers are nominated according to Committer Promotion Process.

SSH

Most users use SSH to authenticate with remote servers. To perform such authentication with Gerrit, your have to provide your SSH Public key to Gerrit (User Account->Settings->SSH Public keys)
In case you can't use SSH (because network do not allow SSH on port 29418), you can use HTTPS. In such case you need to have Gerrit generating a password for you (User Account->Settings->HTTPS Password->Generate Password).

A couple of other things specific to Gerrit

  • Gerrit does not allow you push directly to your branch. If you're not using the git-review plugin then to push a change against your branch it will be as follows:
Pushing Code into Gerrit
git push origin HEAD:refs/for/$BRANCH

in this case $BRANCH == master
  • Your change will go to Gerrit to be reviewed. It will not be merged onto the branch until someone with committer rights gives it a Code-Review +2. Normally there are verification jobs setup in Jenkins that would vote on the Verified field, but as your project(s) don't just yet (oparent being the exception as they pushed a verify job this afternoon) a committer will also have to flag Verified +1. Once both fields are at max value, then a committer will have the ability to Submit the code. It will not be merged until the final Submit has occurred.

Once the code is submitted, Gerrit moves the code from the Open tab https://gerrit.open-o.org/r/#/q/status:open to the Merged tabs https://gerrit.open-o.org/r/#/q/status:merged.

  • Your code import cannot be a historical import. That is, you can't be bringing history from an external SCM tool into a Gerrit repo under Linux Foundation control. This is a policy Linux Foundation had in place for a very long time and is non-negotiable. This means your import will be a squash commit of any code coming in.

HTTP Sequence of events

--[cut using https syntax]--
export LFID=<YOUR_LFID_HERE>
export REPO=common-services-external-system-registration
git clone https://${LFID}@gerrit.open-o.org/r/a/${REPO}.git
cd ${REPO}
# acquire the commit hook
curl -Lo ./git/hooks/commit-msg https://gerrit.open-o.org/r/tools/hooks/commit-msg
chmod +x ./git/hooks/commit-msg
# create your code commit
cp ${codeblob} ./
git add .
git commit -asm 'Initial code import'
git push origin HEAD:refs/for/master
--[/cut using https syntax]--

A couple of things to note here:

The URL will be /r/a/${REPO}.git (the .git is optional) /r == the web url that Gerrit lives on. 
/a == authenticated https. 
Without /a it will try to do an anonymous http connection and it will fail for pushes, at least when we open the repos to public access.

The commit has a -s which gives you the 'Signed-off-by: Name <email>' footer in your commit message. Your 'Name <email>' portion must match what Gerrit has registered. And it's case sensitive.

If you do not have the Gerrit commit hook installed you'll get an error when you push telling you how to get it. Once you've obtained it you'll want to run the following operation before trying to push again:

--[cut]--
git commit --amend
--[/cut]--

Just resave your commit message. After you do that if you do a 'git log' you should notice that a 'Change-Id:' line was added above your 'Signed-off-by' footer. This Change-Id is required by Gerrit.

SSH Sequence of events

--[cut using ssh syntax]--
export LFID=<YOUR_LFID_HERE>
export REPO=common-services-external-system-registration
git clone ssh://${LFID}@gerrit.open-o.org:29418/${REPO}.git
cd ${REPO}
# acquire the commit hook
curl -Lo .git/hooks/commit-msg https://gerrit.open-o.org/r/tools/hooks/commit-msg
chmod +x .git/hooks/commit-msg
# creat your code commit
cp ${codeblob} ./
git add .
git commit -asm 'Initial code import'
git push origin HEAD:refs/for/master
--[/cut using ssh syntax]--

You'll note that this is essentially the same. The primary difference is that you won't be getting prompted for a password as it only operates with SSH keys.

Speaking of passwords. The HTTPS method does not use your LFID password, you need to have Gerrit generate one for you: Login -> select your name in the right corner -> Settings -> HTTP Password -> Generate Password

Committer

In order to avoid delay into merging the code, it is expected that committer do review the code within the next 24 hours after the contributor has submitted his code.
There are 2 ways for a Committer to be notified by email on the code to review:

  1. the contributor specifically enter the committer name in the submission form.
  2. the contributor updates his Gerrit's settings to Watch his projects.

Things to keep in your radar

Merge Conflict


It may happen that you cannot merge into the upper branch. Gerrit will render this behavior by indicating in the Status column the message Merge Conflict.
You can also run the following query to display all the submissions in status Merge Conflict.

To address the Merge Conflict issue 3 solution scenarios are possible:

  1. A change that has already been merged is in conflict with the current change, try to rebase the change. If that doesn't resolve the issue then try the next solution.
  2. A simple rebase can't fix the problem because it is fundamentally unsolvable without making actual changes to the submission. The solution to this sort of error is to try to do the merge locally and find out what the actual problem is and then re-submit an update.
  3. Abandoning and bringing in a new patch. This is of a last resort because you can't figure out what the real problem is.

Jenkins Intermittent Failure

For some yet unknown reason it may happen that Jenkins have intermittent failure and thus impact your build.
Look for typical message:

 

[ssh-agent] FATAL: Could not find a suitable ssh-agent provider
[ssh-agent] Diagnostic report
[ssh-agent]  Java/JNR ssh-agent
[ssh-agent] hudson.remoting.RequestAbortedException: java.io.IOException: Unexpected termination of the channel
................
FATAL: [ssh-agent] Unable to start agent
hudson.util.IOException2: [ssh-agent] Unable to start agent
................
Finished: FAILURE


To address the issue just hit the reply button in Gerrit add keyword 'recheck' or 'reverify' (do not enter the ') to the submission that failed. This will automatically retrigger the verify job.
If the job was a merge job, then use the 'remerge' keyword. It will automatically retrigger the merge job.