Gerrit Code Review - Access Controls

Gerrit comes with 4 system groups, with special access privileges and membership management. The identity of these groups is set in the system_config table within the database, so the groups can be renamed after installation if desired.

This is the Gerrit "root" identity.

Users in the Administrators group can perform any action under the Admin menu, to any group or project, without further validation of any other access controls. In most installations only those users who have direct filesystem and database access would be placed into this group.

Membership in the Administrators group does not imply any other access rights. Administrators do not automatically get code review approval or submit rights in projects. This is a feature designed to permit administrative users to otherwise access Gerrit as any other normal user would, without needing two different accounts.

All users are automatically a member of this group. Users who are not signed in are a member of only this group, and no others.

Any access rights assigned to this group are inherited by all users.

Administrators and project owners can grant access rights to this group in order to permit anonymous users to view project changes, without requiring sign in first. Currently it is only worthwhile to grant Read Access to this group as Gerrit requires an account identity for all other operations.

All signed-in users are automatically a member of this group (and also Anonymous Users, see above).

Any access rights assigned to this group are inherited by all users as soon as they sign-in to Gerrit. If OpenID authentication is being employed, moving from only Anonymous Users into this group is very easy. Caution should be taken when assigning any permissions to this group.

It is typical to assign Code Review -1..+1 to this group, allowing signed-in users to vote on a change, but not actually cause it to become approved or rejected.

Registered users are always permitted to make and publish comments on any change in any project they have Read Access to.

Access rights assigned to this group are always evaluated within the context of a project and are resolved to access rights for all users which own the project.

By assigning access rights to this group on a parent project Gerrit administrators can define a set of default access rights for project owners. Child projects inherit these access rights where they are resolved to the users that own the child project. Having default access rights for projects owners assigned on a parent project may avoid the need to initially configure access rights for newly created child projects.

Account groups contain a list of zero or more user account members, added individually by a group owner. Any user account listed as a group member is given any access rights granted to the group.

Every group has one other group designated as its owner. Users who are members of the owner group can:

It is permissible for a group to own itself, allowing the group members to directly manage who their peers are.

Newly created groups are automatically created as owning themselves, with the creating user as the only member. This permits the group creator to add additional members, and change the owner to another group if desired.

It is somewhat common to create two groups at the same time, for example Foo and Foo-admin, where the latter group Foo-admin owns both itself and also group Foo. Users who are members of Foo-admin can thus control the membership of Foo, without actually having the access rights granted to Foo. This configuration can help prevent accidental submits when the members of Foo have submit rights on a project, and the members of Foo-admin typically do not need to have such rights.

A system wide access control list affecting all projects is stored in project "\-- All Projects \--". This inheritance can be configured through gerrit set-project-parent.

Per-project access control lists are also supported.

Users are permitted to use the maximum range granted to any of their groups in an approval category. For example, a user is a member of Foo Leads, and the following ACLs are granted on a project:

Then the effective range permitted to be used by the user is -2..+2, as the user is a member of all three groups (see above about the system groups) and the maximum range is chosen (so the lowest value granted to any group, and the highest value granted to any group).

Reference-level access control is also possible.

Permissions can be set on a single reference name to match one branch (e.g. refs/heads/master), or on a reference namespace (e.g. refs/heads/\*) to match any branch starting with that prefix. So a permission with refs/heads/\* will match refs/heads/master and refs/heads/experimental, etc.

Reference names can also be described with a regular expression by prefixing the reference name with \^. For example \^refs/heads/[a-z]\{1,8\} matches all lower case branch names between 1 and 8 characters long. Within a regular expression . is a wildcard matching any character, but may be escaped as \.. The dk.brics.automaton library is used for evaluation of regular expression access control rules. See the library documentation for details on this particular regular expression flavor.

References can have the current user name automatically included, creating dynamic access controls that change to match the currently logged in user. For example to provide a personal sandbox space to all developers, refs/heads/sandbox/$\{username\}/* allowing the user joe to use refs/heads/sandbox/joe/foo.

When evaluating a reference-level access right, Gerrit will use the full set of access rights to determine if the user is allowed to perform a given action. For example, if a user is a member of Foo Leads, they are reviewing a change destined for the refs/heads/qa branch, and the following ACLs are granted on the project:

Then the effective range permitted to be used by the user is -2..+2, as the user’s membership of Foo Leads effectively grant them access to the entire reference space, thanks to the wildcard.

Gerrit also supports exclusive reference-level access control.

It is possible to configure Gerrit to grant an exclusive ref level access control so that only users of a specific group can perform an operation on a project/reference pair. This is done by prefixing the reference specified with a '-'.

For example, if a user who is a member of Foo Leads tries to review a change destined for branch refs/heads/qa in a project, and the following ACLs are granted:

Then this user will not have Code Review rights on that change, since there is an exclusive access right in place for the refs/heads/qa branch. This allows locking down access for a particular branch to a limited set of users, bypassing inherited rights and wildcards.

In order to grant the ability to Code Review to the members of Foo Leads, in refs/heads/qa then the following access rights would be needed:

If the Gerrit instance is configured to use OpenID authentication, an account’s effective group membership will be restricted to only the Anonymous Users and Registered Users groups, unless all of its OpenID identities match one or more of the patterns listed in the auth.trustedOpenID list from gerrit.config.

Any access right granted to a group within \-- All Projects \-- is automatically inherited by every other project in the same Gerrit instance. These rights can be seen, but not modified, in any other project’s Access administration tab.

Only members of the group Administrators may edit the access control list for \-- All Projects \--.

Ownership of this project cannot be delegated to another group. This restriction is by design. Granting ownership to another group gives nearly the same level of access as membership in Administrators does, as group members would be able to alter permissions for every managed project.

The per-project ACL is evaluated before the global \-- All Projects \-- ACL, permitting some limited override capability to project owners. This behavior is generally only useful on the Read Access category when granting -1 No Access within a specific project to deny access to a group.

Gerrit comes pre-configured with several default categories that can be granted to groups within projects, enabling functionality for that group’s members.

The Owner category controls which groups can modify the project’s configuration. Users who are members of an owner group can:

Note that project owners implicitly have branch creation or deletion through the web UI, but not through SSH. To get SSH branch access project owners must grant an access right to a group they are a member of, just like for any other user.

Ownership over a particular branch subspace may be delegated by entering a branch pattern. To delegate control over all branches that begin with qa/ to the QA group, add Owner category for reference refs/heads/qa/\*. Members of the QA group can further refine access, but only for references that begin with refs/heads/qa/.

The Read Access category controls visibility to the project’s changes, comments, code diffs, and Git access over SSH or HTTP. A user must have Read Access +1 in order to see a project, its changes, or any of its data.

This category has a special behavior, where the per-project ACL is evaluated before the global all projects ACL. If the per-project ACL has granted Read Access -1, and does not otherwise grant Read Access \+1, then a Read Access +1 in the all projects ACL is ignored. This behavior is useful to hide a handful of projects on an otherwise public server.

For an open source, public Gerrit installation it is common to grant Read Access +1 to Anonymous Users in the \-- All Projects \-- ACL, enabling casual browsing of any project’s changes, as well as fetching any project’s repository over SSH or HTTP. New projects can be temporarily hidden from public view by granting Read Access -1 to Anonymous Users and granting Read Access +1 to the project owner’s group within the per-project ACL.

For a private Gerrit installation using a trusted HTTP authentication source, granting Read Access +1 to Registered Users may be more typical, enabling read access only to those users who have been able to authenticate through the HTTP access controls. This may be suitable in a corporate deployment if the HTTP access control is already restricted to the correct set of users.

The Read Access +2 permits the user to upload a non-merge commit to the project’s refs/for/BRANCH namespace, creating a new change for code review.

Rather than place this permission in its own category, its chained into the Read Access category as a higher level of access. A user must be able to clone or fetch the project in order to create a new commit on their local system, so in practice they must also have Read Access +1 to even develop a change. Therefore upload access implies read access by simply being a higher level of it.

For an open source, public Gerrit installation, it is common to grant Read Access +1..+2 to Registered Users in the \-- All Projects \-- ACL. For more private installations, its common to simply grant Read Access +1..+2 to all users of a project.

The Read Access +3 permits the user to upload merge commits, but is otherwise identical to Read Access +2. Some projects wish to restrict merges to being created by Gerrit. By granting, Read Access +1..+2, the only merges that enter the system will be those created by Gerrit, or those pushed directly.

This category permits users to push an annotated tag object over SSH into the project’s repository. Typically this would be done with a command line such as:

Tags must be annotated (created with git tag -a or git tag -s), should exist in the refs/tags/ namespace, and should be new.

This category is intended to be used to publish tags when a project reaches a stable release point worth remembering in history.

The range of values is:

To push tags created by users other than the current user (such as tags mirrored from an upstream project), Forge Identity +2 must be also granted in addition to Push Tag >= +1.

To push lightweight (non annotated) tags, grant Push Branch +2 Create Branch for reference name refs/tags/*, as lightweight tags are implemented just like branches in Git.

To delete or overwrite an existing tag, grant Push Branch +3 Force Push Branch; Delete Branch for reference name refs/tags/*, as deleting a tag requires the same permission as deleting a branch.

This category permits users to push directly into a branch over SSH, bypassing any code review process that would otherwise be used.

This category has several possible values:

This category is primarily useful for projects that only want to take advantage of Gerrit’s access control features and do not need its code review functionality. Projects that need to require code reviews should not grant this category.

Normally Gerrit requires the author and the committer identity lines in a Git commit object (or tagger line in an annotated tag) to match one of the registered email addresses of the uploading user. This permission allows users to bypass that validation, which may be necessary when mirroring changes from an upstream project.

The verified category can have any meaning the project desires. It was originally invented by the Android Open Source Project to mean compiles, passes basic unit tests.

The range of values is:

In order to submit a change, the change must have a +1 Verified in this category from at least one authorized user, and no -1 Fails from an authorized user. Thus, -1 Fails can block a submit, while +1 Verified enables a submit.

If a Gerrit installation does not wish to use this category in any project, it can be deleted from the database:

If a Gerrit installation wants to modify the description text associated with these category values, the text can be updated in the name column of the category_id = \'VRIF' rows in the approval_category_values table.

Additional values could also be added to this category, to allow it to behave more like Code Review (below). Insert -2 and +2 value rows into the approval_category_values with category_id set to VRIF to get the same behavior.

The code review category can have any meaning the project desires. It was originally invented by the Android Open Source Project to mean I read the code and it seems reasonably correct.

The range of values is:

In order to submit a change, the change must have a +2 Looks good to me, approved in this category from at least one authorized user, and no -2 Do not submit from an authorized user. Thus -2 can block a submit, while +2 can enable it.

If a Gerrit installation does not wish to use this category in any project, it can be deleted from the database:

If a Gerrit installation wants to modify the description text associated with these category values, the text can be updated in the name column of the category_id = \'CRVW' rows in the approval_category_values table.

Additional values could be inserted into approval_category_values to further extend the negative and positive range, but there is likely little value in doing so as this only expands the middle region. This category is a MaxWithBlock type, which means that the lowest negative value if present blocks a submit, while the highest positive value is required to enable submit.

There is also a MaxNoBlock category which still requires the highest positive value to submit, but the lowest negative value will not block the change, and does not carry over between patch sets. This level is mostly useful for automated code-reviews that may have false-negatives that shouldn’t block the change.

This category permits users to push the Submit Patch Set n button on the web UI.

Submitting a change causes it to be merged into the destination branch as soon as possible, making it a permanent part of the project’s history.

In order to submit, all approval categories (such as Verified and Code Review, above) must enable submit, and also must not block it. See above for details on each category.

Gerrit administrators can also make up their own categories.

See above for descriptions of how Verified and Code Review work, and insert your own category with function_name = \'MaxWithBlock' to get the same behavior over your own range of values, in any category you desire.

Ensure category_id is unique within your approval_categories table. The default values VRIF and CVRF used for the categories described above are simply that, defaults, and have no special meaning to Gerrit. The other standard category_id values like OWN, READ, SUBM, pTAG and pHD have special meaning and should not be modified or reused.

The position column of approval_categories controls which column of the Approvals table the category appears in, providing some layout control to the administrator.

All MaxWithBlock categories must have at least one positive value in the approval_category_values table, or else submit will never be enabled.

To permit blocking submits, ensure a negative value is defined for your new category. If you do not wish to have a blocking submit level for your category, do not define values less than 0.

Keep in mind that category definitions are currently global to the entire Gerrit instance, and affect all projects hosted on it. Any change to a category definition affects everyone.

For example, to define a new 3-valued category that behaves exactly like Verified, but has different names/labels:

The new column will appear at the end of the table (in position 3), and -1 Do not have copyright will block submit, while +1 Copyright clear is required to enable submit.