This is a Gerrit guide that is dedicated to project owners. It
explains the many possibilities that Gerrit provides to customize the
workflows for a project.

What is a project owner?

Being project owner means that you own a project in Gerrit.
Technically this is expressed by having the
Owner access right on
refs/* on that project. As project owner you have the permission to
edit the access control list and the project settings of the project.
It also means that you should get familiar with these settings so that
you can adapt them to the needs of your project.

Being project owner means being responsible for the administration of
a project. This requires having a deeper knowledge of Gerrit than the
average user. Normally per team there should be 2 to 3 persons, who
have a certain level of Git/Gerrit knowledge, assigned as project
owners. It normally doesn’t make sense that everyone in a team is
project owner. For normal team members it is sufficient to be committer
or contributor.

Access Rights

As a project owner you can edit the access control list of your
project. This allows you to grant permissions on the project to
different groups.

Gerrit comes with a rich set of permissions which allow a very
fine-grained control over who can do what on a project. Access
control is one of the most powerful Gerrit features but it is also a
rather complex topic. This guide will only highlight the most
important aspects of access control, but the
Access Control chapter explains all the details.

Editing Access Rights

To see the access rights of your project

go to the Gerrit Web UI

click on the Projects > List menu entry

find your project in the project list and click on it

click on the Access menu entry

By clicking on the Edit button the access rights become editable and
you may save any changes by clicking on the Save Changes button.
Optionally you can provide a Commit Message to explain the reasons
for changing the access rights.

The access rights are stored in the project’s Git repository in a
special branch called refs/meta/config. On this branch there is a
project.config file which contains the access rights. More
information about this storage format can be found in the
Project Configuration File Format
chapter. What is important to know is that by looking at the history
of the project.config file on the refs/meta/config branch you can
always see how the access rights were changed and by whom. If a good
commit message is provided you can also see from the history why the
access rights were modified.

If a Git browser such as gitweb is configured for the Gerrit server you
can find a link to the history of the project.config file in the
Web UI. Otherwise you may inspect the history locally. If you have
cloned the repository you can do this by executing the following
commands:

Non project owners may still edit the access rights and propose the
modifications to the project owners by clicking on the Save for
Review button. This creates a new change with the access rights
modifications that can be approved by a project owner. The project
owners are automatically added as reviewer on this change so that they
get informed about it by email.

Inheritance

Normally when a new project is created in Gerrit it already has some
access rights which are inherited from the parent projects.
Projects in Gerrit are organized hierarchically as a tree with the
All-Projects project as root from which all projects inherit. Each
project can have only a single parent project, multi-inheritance is
not supported.

Looking at the access rights of your project in the Gerrit Web UI, you
only see the access rights which are defined on that project. To see
the inherited access rights you must follow the link to the parent
project under Rights Inherit From.

Inherited access rights can be overwritten unless they are defined as
BLOCK rule. BLOCK rules are used to
limit the possibilities of the project owners on the inheriting
projects. With this, global policies can be enforced on all projects.
Please note that Gerrit doesn’t prevent you from assigning access
rights that contradict an inherited BLOCK rule, but these access rights
will simply have no effect.

If you are responsible for several projects which require the same
permissions, it makes sense to have a common parent for them and to
maintain the access rights on that common parent. Changing the parent
of a project is only allowed for Gerrit administrators. This means you
need to contact the administrator of your Gerrit server if you want to
reparent your project. One way to do this is to change the parent
project in the Web UI, save the modifications for review and get the
change approved and merged by a Gerrit administrator.

References

Access rights in Gerrit are assigned on references (aka refs). Refs in
Git exist in different namespaces, e.g. all branches normally exist
under refs/heads/ and all tags under refs/tags/. In addition there
are a number of special refs
and magic refs.

Access rights can be assigned on a concrete ref, e.g.
refs/heads/master but also on ref patterns and regular expressions
for ref names.

A ref pattern ends with /* and describes a complete ref name
namespace, e.g. access rights assigned on refs/heads/* apply to all
branches.

Regular expressions must start with ^, e.g. access rights assigned
on ^refs/heads/rel-.* would apply to all rel-* branches.

Groups

Access rights are granted to groups. It is useful to know that Gerrit
maintains its own groups internally but also supports different external
group backends.

The Gerrit internal groups can be seen in the Gerrit Web UI by clicking
on the Groups > List menu entry. By clicking on a group you can
edit the group members (Members tab) and the group options
(General tab).

Gerrit internal groups contain users as members, but can also include
other groups, even external groups.

Every group is owned by an owner group. Only members of the owner
group can administrate the owned group (assign members, edit the group
options). A group can own itself; in this case members of the group
can, for example, add further members to the group. When you create new
groups for your project to assign access rights to committer or other
roles, make sure that they are owned by the project owner group.

An important setting on a group is the option
Make group visible to all registered users., which defines whether
non-members can see who is member of the group.

New internal Gerrit groups can be created under Groups >
Create New Group. This menu is only available if you have the global
capability Create Group
assigned.

Gerrit also has a set of special
system groups that you might
find useful.

External groups need to be prefixed when assigning access rights to
them, e.g. LDAP group names need
to be prefixed with ldap/.

If the
singleusergroup plugin is installed you can also directly assign
access rights to users, by prefixing the username with user/ or the
user’s account ID by userid/.

Common Access Rights

Different roles in a project, such as developer (committer) or
contributor, need different access rights. Examples for which access
rights are typically assigned for which role are described in the
Access Control chapter.

Code Review

Gerrit’s main functionality is code review, however using code review
is optional and you may decide to only use Gerrit as a Git server with
access control. Whether you allow only pushes for review or also
direct pushes depends on the project’s access rights.

To push a commit for review it must be pushed to
refs/for/<branch-name>. This means
the Push access right
must be assigned on refs/for/<branch-name>.

To allow direct pushes and bypass code review, the
Push access right is
required on refs/heads/<branch-name>.

By pushing for review you are not only enabling the review workflow,
but you can also get automatic
verifications from a build server before changes are merged. In
addition you can benefit from Gerrit’s merge strategies that can
automatically merge/rebase commits on server side if necessary. You can
control the merge strategy by configuring the
submit type on the project. If you
bypass code review you always need to merge/rebase manually if the tip
of the destination branch has moved. Please keep this in mind if you
choose to not work with code review because you think it’s easier to
avoid the additional complexity of the review workflow; it might
actually not be easier.

You may also enable auto-merge on
push to benefit from the automatic merge/rebase on server side while
pushing directly into the repository.

Project Options

As project owner you can control several options on your project.
The different options are described in the
Project Options section.

To see the options of your project:

Go to the Gerrit Web UI.

Click on the Projects > List menu entry.

Find your project in the project list and click it.

Click the General menu entry.

Submit Type

An important decision for a project is the choice of the submit type
and the content merge setting (see the Allow content merges option).
The submit type is the method
Gerrit uses to submit a change to the project. The submit type defines
what Gerrit should do on submit of a change if the destination branch
has moved while the change was in review. The
content merge setting applies
if the same files have been modified concurrently and tells Gerrit
whether it should attempt a content merge for these files.

When choosing the submit type and the content merge setting one must
weigh development comfort against the safety of not breaking the
destination branch.

The most restrictive submit type is
Fast Forward Only. Using
this submit type means that after submitting one change all other open
changes for the same destination branch must be rebased manually. This
is quite burdensome and in practice only feasible for branches with
very few changes. On the other hand, if changes are verified before
submit, e.g. automatically by a CI integration, with this submit type,
you can be sure that the destination branch never gets broken.

Choosing Merge If Necessary
as submit type makes the life for developers more comfortable,
especially if content merge is enabled. If this submit strategy is used
developers only need to rebase manually if the same files have been
modified concurrently or if the content merge on such a file fails. The
drawback with this submit type is that there is a risk of breaking
the destination branch, e.g. if one change moves a class into another
package and another change imports this class from the old location.
Experience shows that in practice Merge If Necessary with content
merge enabled works pretty well and breaking the destination branch
happens rarely. This is why this setting is recommended at least for
development branches. You likely want to start with
Merge If Necessary with content merge enabled and only switch to a
more restrictive policy if you are facing issues with the build and
test stability of the destination branches.

It is also possible to define the submit type dynamically via
Prolog. This way you can use different submit
types for different branches.

Please note that there are other submit types available; they are
described in the Submit Type
section.

Labels

The code review process includes that reviewers formally express their
opinion about a change by voting on different
labels. By default Gerrit comes with the
Code-Review label and many
Gerrit servers have the Verified
label configured globally. However projects can also define their own
custom labels to formalize
project-specific workflows. For example if a project requires an IP
approval from a special IP-team, it can define an IP-Review label
and grant permissions to the IP-team to vote on this label.

The behavior of a label can be controlled by its
function, e.g. it can be
configured whether a max positive voting on the label is required for
submit or if the voting on the label is optional.

By using a custom submit rule it can be controlled
per change whether a label is required for submit or not.

A useful feature on labels is the possibility to automatically copy
scores forward to new patch sets if it was a
trivial
rebase or if
there was no code change (e.g. only the commit message was edited).

Submit Rules

A submit rule in Gerrit is logic
that defines when a change is submittable. By default, a change is
submittable when it gets at least one highest vote on each label and
has no lowest vote (aka veto vote) on any label.

The submit rules in Gerrit are implemented in
Prolog and projects that need more flexibility can define their own
submit rules to decide when a change should be submittable. A good
example from the Prolog
cookbook shows how to allow submit only if a change has a
Code-Review+2 vote from a person that is not the change author. This
way a four-eyes principle for the reviews can be enforced.

A Prolog submit rule has access to
information about the change for which it is testing the
submittability. Among others the list of the modified files can be
accessed, which allows special logic if certain files are touched. For
example, a common practice is to require a vote on an additional label,
like Library-Compliance, if the dependencies of the project are
changed.

It is also possible to control the
submit type from Prolog. For example this can be used to define a more
restrictive submit type such as Fast Forward Only for stable branches
while using a more liberal submit type, e.g. Merge If Necessary with
content merge, for development branches. How this can be done can be
seen from an example in
the Prolog cookbook.

Submit rules are maintained in the
rules.pl file in the refs/meta/config branch of the project. How to
write submit rules is explained in the
Prolog cookbook. There
is also good support for
testing submit rules while developing them.

Continuous Integration

With Gerrit you can have continuous integration builds not only for
updates of central branches but also whenever a new change/patch set is
uploaded for review. This way you get automatic verification of all
changes before they are merged and any build and test issues are
detected early. To indicate the build and test status the continuous
integration system normally votes with the
Verified label on the change.

There are several solutions for integrating continuous integration
systems. The most commonly used are:

For the integration with the continuous integration system you must
have a service user that is able to access Gerrit. To create a service
user in Gerrit you can use the create-account
SSH command if the
Create Account global capability is granted. If not, you need to ask
a Gerrit administrator to create the service user.

If the
serviceuser plugin is installed you can also create new service users
in the Gerrit Web UI under People > Create Service User. For this
the Create Service User global capability must be assigned.

The service user must have read
access to your project. In addition, if automatic change verification
is enabled, the service user must be allowed to vote on the
Verified label.

Continuous integration systems usually integrate with Gerrit by
listening to the Gerrit stream
events. For this the service user must have the
Stream Events global
capability assigned.

Commit Validation

Gerrit provides an
extension point to do validation of new commits. A Gerrit plugin
implementing this extension point can perform validation checks when
new commits are pushed to Gerrit. The plugin can either provide a
message to the client or reject the commit and cause the push to fail.

By setting HEAD on the project you can define its
default branch. For convenience
reasons, when the repository is cloned Git creates a local branch for
this default branch and checks it out.

Email Notifications

With Gerrit individual users control their own email subscriptions. By
editing the watched projects in the Web UI
under Settings > Watched Projects users can decide which events to
be informed about by email. The change notifications can be filtered by
change search expressions.

This means as a project owner you normally don’t need to do anything
about email notifications, except maybe telling your project team where
to configure the watches.

Gerrit also supports notifications on
project level that allow project owners to set up email notifications
for team mailing lists or groups of users. This configuration is done
in the project.config file in the refs/meta/config branch as
explained in the section about project
level notifications.

Dashboards

Gerrit comes with a pre-defined user dashboard that provides a view
of the changes that are relevant for a user. Users can also define
their own custom dashboards where the
dashboard sections can be freely configured. As a project owner you can
configure such custom dashboards on
project level. This way
you can define a view of the changes that are relevant for your
project and share this dashboard with all users. The project dashboards
can be seen in the Web UI under Projects > List > <your project> >
Dashboards.

Issue Tracker Integration

There are several possibilities to integrate issue trackers with
Gerrit.

Comment Links

As described in the Comment Links section, comment
links can be used to link IDs from commit message footers to issues in
an issue tracker system.

Tracking IDs

Gerrit can be configured to index IDs from commit message footers so
that the tr/bug search operators can be used
to query for changes with a certain ID. The
configuration of tracking IDs can
only be done globally by a Gerrit administrator.

Issue Tracker System Plugins

There are Gerrit plugins for a tight integration with
Jira,
Bugzilla and
IBM Rational Team Concert.
If installed, these plugins can e.g. be used to automatically add links
to Gerrit changes to the issues in the issue tracker system or to
automatically close an issue if the corresponding change is merged.
If installed, project owners may enable/disable the issue tracker
integration from the Gerrit Web UI under Projects > Lists >
<your project> > General.

Comment Links

Gerrit can linkify strings in commit messages, summary comments and
inline comments. A string that matches a defined regular expression is
then displayed as hyperlink to a configured backend system.

So called comment links can be configured globally by a Gerrit
administrator, but also per project by the project owner. Comment links
on project level are defined in the project.config file in the
refs/meta/config branch of the project as described in the
documentation of the commentlink
configuration parameter.

Often comment links are used to link an ID in a commit message footer
to an issue in an issue tracker system. For example, to link the ID
from the Bug footer to Jira the following configuration can be used:

Reviewers

Normally it is not needed to explicitly assign reviewers to every
change since the project members either
watch the project and get notified by email or regularly check the
list of open changes in the Gerrit Web UI. The project members then
pick the changes themselves that are interesting to them for review.

If authors of changes want to have a review by a particular person
(e.g. someone who is known to be expert in the touched code area, or a
stakeholder for the implemented feature), they can request the review
by adding this person in the Gerrit Web UI as a reviewer on the change.
Gerrit will then notify this person by email about the review request.

With the
reviewers plugin it is possible to configure default reviewers who
will be automatically added to each change. The default reviewers can
be configured in the Gerrit Web UI under Projects > List >
<your project> > General in the reviewers Plugin section.

The
reviewers-by-blame plugin can automatically add reviewers to changes
based on the
git blame computation on the changed files. This means that the plugin
will add those users as reviewer that authored most of the lines
touched by the change, since these users should be familiar with the
code and can most likely review the change. How many reviewers the
plugin will add to a change at most can be configured in the Gerrit
Web UI under Projects > List > <your project> > General in the
reviewers-by-blame Plugin section.

Download Commands

On the change screen in the Downloads drop-down panel Gerrit offers
commands for downloading the currently viewed patch set.

The download commands are implemented by Gerrit plugins. This means
that the available download commands depend on the installed Gerrit
plugins:

The project-download-commands plugin enables project owners to
configure project-specific download commands. For example, a
project-specific download command may update submodules, trigger a
build, execute the tests or even do a deployment.

The project-specific download commands must be configured in the
project.config file in the refs/meta/config branch of the project:

Project-specific download commands that are defined on a parent project
are inherited by the child projects. A child project can overwrite an
inherited download command, or remove it by assigning no value to it.

Theme

Gerrit supports project-specific themes for customizing the appearance
of the change screen and the diff screens. It is possible to define an
HTML header and footer and to adapt Gerrit’s CSS. Details about themes
are explained in the Themes section.

Project-specific themes can only be installed by Gerrit administrators
since the theme files must be copied into the Gerrit installation
folder.

Integration with other tools

Gerrit provides many possibilities for the integration with other
tools:

Stream Events:

The stream-events SSH command allows to
listen to Gerrit events. Other
tools can use this to react on actions done in Gerrit.

The Stream Events
global capability is required for using the stream-events command.

REST API:

Gerrit provides a rich REST API that other tools
can use to query information from Gerrit and and to trigger actions in
Gerrit.

Gerrit Plugins:

The Gerrit functionality can be extended by plugins and there are many
extension points, e.g. plugins can

Project Lifecycle

Project Creation

New projects can be created in the Gerrit Web UI under Projects >
Create Project. The Create Project menu entry is only available if
you have the
Create Project global capability assigned.

Projects can also be created via REST or SSH as described in the
Project Setup section.

Creating the project with an initial empty commit is generally
recommended because some tools have issues with cloning repositories
that are completely empty. However, if you plan to
import an existing history into the new project, it is better to
create the project without an initial empty commit.

Import Existing History

If you have an existing history you can import it into a Gerrit
project. To do this you need to have a local Git repository that
contains this history. If your existing codebase is in another VCS you
must migrate it to Git first. For Subversion you can use the
git svn command as described in the
Subversion migration guide. An importer for Perforce is available in
the contrib section of the Git source code; how to use
git p4 to do the import from
Perforce is described in the
Perforce migration guide.

To import an existing history into a Gerrit project you bypass code
review and push it directly to refs/heads/<branch>. For this you must
have the corresponding
Push access right assigned. If the destination branch in the Gerrit
repository already contains a history (e.g. an initial empty commit),
you can overwrite it by doing a force push. In this case force push
must be allowed in the access controls of the project.

Some Gerrit servers may disallow forging committers by blocking the
Forge Committer
access right globally. In this case you must use the
git filter-branch command to rewrite the committer information for all
commits (the author information that records who was writing the code
stays intact; signed tags will lose their signature):

If a max object size
limit is configured on the server you may need to remove large objects
from the history before you are able to push. To find large objects in
the history of your project you can use the reposize.sh script which
you can download from Gerrit:

Since this command rewrites all commits in the repository it’s a good
idea to create a fresh clone from this rewritten repository before
pushing to Gerrit, this will ensure that the original objects which
have been rewritten are removed.

Project Deletion

Gerrit core does not support the deletion of projects.

If the
delete-project plugin is installed, projects can be deleted from the
Gerrit Web UI under Projects > List > <project> > General by
clicking on the Delete command under Project Commands. The Delete
command is only available if you have the Delete Projects global
capability assigned, or if you own the project and you have the
Delete Own Projects global capability assigned. If neither of these
capabilities is granted, you need to contact a Gerrit administrator to
request the deletion of your project.

Instead of deleting a project you may set the
project state to ReadOnly or
Hidden.