CollabNet Gerrit Notifications – For all who miss the good ol’ git push notifications

The main feature of our latest TeamForge-Git-Integration (8.0.6) is a brand new notification plugin for Gerrit.

This is exciting news to anybody who was used to the git push notifications of the git multimail script. It will also make sure you never miss an accidental git history rewrite again – even if you are not a Gerrit Administrator. This blog post explains the motivation behind this new feature and how to configure it.

Motivation

Gerrit is a very powerful Git server implementation. It introduces unmatched code review and access right enforcement capabilities. Gerrit is used in many mission critical, large scale communities like the Android Open Source Project and thousands of companies. Because of its superior performance, vibrant community and unmatched features mentioned above, it is CollabNet’s choice for the technical foundation of our TeamForge Git-Integration.

Gerrit can be configured to send out email notifications whenever a review/change set changes. However, Gerrit is “silent” (will not send out any notifications) if you do not use its review workflow and simply push changes directly to a branch. Let’s be honest: Not all Gerrit users are interested in code reviews but would like to benefit from its performance and incredible flexible access right model. Those users treat Gerrit like an ordinary Git backend and will push directly to remote branches. As long as Gerrit is not sending out any emails for their preferred development workflow, this is problematic for certain stakeholders, mainly project managers, product owners and release managers who periodically review their inboxes in order to track project/feature velocity but do not typically have a git command line at hand. Some of them might not even have direct access to the Git repository content itself but still need a general idea on what is going on.

In an ideal world one would just have to …

• create a TeamForge forum (acts as mailing list as well)
• add the interested stakeholders to it (or let them monitor themselves)
• configure access rights for that forum (standard TeamForge RBAC)

… and finally tell Gerrit to post all git push activities to that forum.

This is exactly what our new Gerrit notification plugin provides…

Seeing the Notification Plugin in action

I have a TeamForge forum (also acts as mailing list) called Development with stakeholders already subscribed to it and told Gerrit to send information about pushed changes and history rewrites to it (detailed setup is described later in this post). I also setup a Git repository global_ventures with 2 commits and 1 tag created locally that were pushed back to origin. Here is the corresponding forum update:

Note that all changes introduced with this RefUpdate operation (2 commits and 1 tag) are nicely grouped in a single forum topic. The main topic’s post contains the summary of all git push changes so that going over details is not necessary in order to get an impression of what was changed. Further details can be found in the subsequent commits posts.

The value of those notification mails gets even clearer when a history rewrite operation got performed. Here is the result of a git forced push operation that swaps a commit with a new one:

Once again all changes are wrapped into one topic with a summary post first and nested detail posts.

If this feature looks exciting to you and you like to find out how to configure read on …

Development forum configuration setup

Step 1: Create a TeamForge discussion forum that should receive git push notifications

For the sake of simplicity a public forum called Development was created with the following properties:

By default all members of Brokerage System (Sample) project have read and write access to all forums but this might be modified by changing the discussion permissions for the TeamForge project roles in question. As the screenshot below is showing, access to the git repository itself is not necessary in order to read git push notifications in that forum.

Step 2: Configure events notification in Gerrit

In order to configure Gerrit/TeamForge forum notifications, you need to have Gerrit OWN permissions for the git repository in question. If you are part of a TeamForge project role with SCM Admin permissions, you should have this access right. In addition you would need post/view permissions for the TeamForge forum you like to connect with this repository. The screenshot below shows a new menu item “Notification” in Gerrit’s project menu bar which contains all TeamForge specific notification settings.

When you visit this screen for the first time, chances are high that there is no forum set up yet (unless someone else already established that link) which means that no notification will be sent to any TeamForge discussion forum (yet). Let’s press the “Add…” button and type the first character of the forum name you like to add. You should see the list of all forums (of the same TeamForge project) you have read access to which start with the letter you just typed. Once you selected your forum, select which kind of events should be sent to it. Ref Updates covers any git push activities (branch creation, branch deletion, tags, new commits) and History Protection will notify any branch deletions, permanent deletion of history and history rewrites (non fast forward pushes).

In the screenshot below we have configured that Ref Update and History Protection events will be sent to one (in this case Development) forum. You can add many forums if you want though.

That’s it, you have successfully configured our notification feature. If you want to test it on your own TeamForge instance, just update to the latest release:
yum install ctf-git-integration-NG
/opt/collabnet/gerrit/scripts/post-install.py

Techie corner (Gerrit Notification plugin vs TeamForge Commit Objects vs Gerrit Watched Projects Settings)

Some readers may have noticed the similarity of our Gerrit Notifications feature and the emails sent out whenever a TeamForge Commit Object gets created. In fact you benefit from both of them as they are complementary. A TeamForge Commit Object is a generic data structure that covers all aspects of a commit (commit message, creator, date, files affected, operations, revision) which can be abstracted from a particular version control system. In other words the same data structure is used for SVN commits, CVS commits and Git commits pushed to Gerrit. The generic, machine readable format of TeamForge Commit objects makes it possible to use them in version control independent reports. The emails being sent out whenever a TeamForge Commit Object is created are a nice side effect but only cover information about newly created commits, so you will not be informed if an already existing commit got pushed to a different branch, a branch got created or deleted or any tag related operation took place (in contrast to SVN or CVS tags/branches and commits are orthogonal concepts in Git). Furthermore, you need at least read access to the repository in question to get TeamForge Commit object emails.

In contrast, our Gerrit Notification Feature was primarily built to inform all human stakeholders, including those who do not even have read access to the repository in question (but are trusted to have access to the notification forum). It will inform about all push operations to direct branches, including new tags, already known commits and history rewrites. In order to get emails regarding push operations involving Gerrit’s magic review branches, you can use the standard Gerrit Watched Projects settings page. We decided not to include activities on those branches in our Notification plugin as review related emails are mostly relevant to stakeholders who closely work with Gerrit and and know about the Watched Projects settings.