Configuring Gerrit
- 1.1 Info
- 2 Overview
- 3 Tools
- 4 SSH
- 5 HTTP Workaround for Gerrit inside a Corporate firewall/proxy blocking SSH
- 6 A couple of other things specific to Gerrit
- 7 Things to keep in your radar
- 8 Submitting a draft feature
- 9 Running a Command within Gerrit
- 9.1 Run-clm
- 9.2 Run-Sonar
- 9.3 Recheck
- 9.4 Remerge
- 9.5 Please Release
Overview
Gerrit is an Open Source web-based collaborative Code Review tool that integrates with Git.
For all ONAP projects, Gerrit is available at https://gerrit.onap.org and documentation at https://gerrit.onap.org/r/Documentation/index.html
Gerrit offers an extensive search capability by using a query syntax documented at https://gerrit.onap.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 with the Release Manager who will make it happen through the TSC.
Project committers group are setup in the form of onap-gerrit-${PROJECT}-committers. Connect to https://identity.linuxfoundation.org to see which group you are part of.
Committers are nominated according to Configuring Gerrit.
Tools
Whatever OS your are using (Mac, Linux, PC) the following tools must be installed and configured:
git client : to perform all the Git task (clone, pull, branch, checkout,...)
git-review : to submit your code into Gerrit
SSH client : to connect securely to Gerrit server
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.
HTTP Workaround for Gerrit inside a Corporate firewall/proxy blocking SSH
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
# in this case
BRANCH=master
git push origin HEAD:refs/for/$BRANCH
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.onap.org/r/#/q/status:open to the Merged tabs https://gerrit.onap.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
The HTTPS method does not use your LFID password; you need to have Gerrit generate a password for you (User Account->Settings->HTTPS Password->Generate Password). (The details of managing "git" credentials can be found here: https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage.)
Clone using https syntax
export LFID=<YOUR_LFID_HERE>
export REPO=common-services-external-system-registration
# do this once
git config --global credential.helper store
git clone https://${LFID}@gerrit.onap.org/r/a/${REPO}.git
Cloning into '${REPO}'...
Password for 'https://${LFID}@gerrit.onap.org':
# type or paste your generated password above.
# this prompt will only appear once, after that, it will store it in ~/.git-credentials
# and will re-use it for any future repos
cd ${REPO}
# acquire the commit hook - do this once
curl -Lo ./.git/hooks/commit-msg https://gerrit.onap.org/r/tools/hooks/commit-msg
chmod +x ./.git/hooks/commit-msg
# configure remote - do this once
git remote add gerrit https://${LFID}@gerrit.onap.org/r/a/${REPO}
# create your code commit
cp ${codeblob} ./
git add .
git commit -asm 'Initial code import'
git push origin HEAD:refs/for/master
# as an alternative to the above "git push" line:
git review
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. (Commit message example)
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:
Amending commits