Project Owner Guide

To see the access rights of your project

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.

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.

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.

Gerrit only supports tags that are reachable by any ref not owned by Gerrit. This includes branches (refs/heads/*) or custom ref namespaces (refs/my-company/*). Tagging a change ref is not supported. When filtering tags by visibility, Gerrit performs a reachability check and will present the user ony with tags that are reachable by any ref they can see.

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.

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 BROWSE > Groups 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 BROWSE > Groups and then clicking on the CREATE NEW button in the upper right corner. The CREATE NEW button 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/.

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.

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.

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.

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

New projects can be created in the Gerrit Web UI under BROWSE > Repositories and then clicking on the CREATE NEW button in the upper right corner. The CREATE NEW button 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.

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:

You can then use the git filter-branch command to remove the large objects from the history of all branches:

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.

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 BROWSE > Repositories > <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.

Gerrit core does not support the renaming of projects.

If the rename-project plugin is installed, projects can be renamed using the rename-project ssh command.

Find details about prerequisites in the plugin documentation.

If you don’t want to use the rename-project plugin you can perform the following steps as a workaround:

Please note that a drawback of this workaround is that the whole review history (changes, review comments) is lost.

Part of Gerrit Code Review