Gerrit2 - Access Controls

Gerrit comes with 3 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.

Administrators

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 adminstrative users to otherwise access Gerrit as any other normal user would, without needing two different accounts.

Anonymous Users

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.

Registered Users

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.

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.

To keep the schema simple to manage, groups cannot be nested. Only individual user accounts can be added as a member.

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

• Add users to this group

• Remove users from this group

• Change the name of this group

• Change the description of this group

• Change the owner of this group, to another group

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 id 0 (named "-- All Projects --" in a default installation). Only the id is recognized as special by Gerrit.

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).

OpenID Authentication

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.

All Projects

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.

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.

Per-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.

Owner

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

• Change the project description

• Create/delete a branch through the web UI (not SSH)

• Grant/revoke any access rights, including Owner

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.

Read Access

The Read Access category controls visibility to the project's changes, comments, code diffs, and Git access over SSH. A user must have Read Access +1 in order to see a project 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. 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.

Push Annotated Tag

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:

git push ssh://USER@HOST:PORT/PROJECT tag v1.0

Tags must be annotated (created with git tag -a or git tag -s), must exist in the refs/tags/ namespace, and must be new. Deleting and overwriting existing tags is not permitted. Lightweight tags are not permitted.

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:

• +1 Create Signed Tag

  A new signed tag may be created. The tagger email address must be verified for the current user.

• +2 Create Annotated Tag

  A new annotated (unsigned) tag may be created. The tagger email address must be verified for the current user.

• +3 Create Any Tag

  Any new annotated tag may be created. A PGP signature is optional, and any tagger email address may be used. This level is primarily useful for mirroring tags made by an upstream maintainer, outside of Gerrit.

Push 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:

• Update Branch

  Any existing branch can be fast-forwarded to a new commit. Creation of new branches is rejected. Deletion of existing branches is rejected. This is the safest mode as commits cannot be discarded.

• Create Branch

  Implies Update Branch, but also allows the creation of a new branch if the name does not not already designate an existing branch name. Like update branch, existing commits cannot be discarded.

• Force Push Branch; Delete Branch

  Implies both Update Branch and Create Branch, but also allows an existing branch to be deleted. Since a force push is effectively a delete immediately followed by a create, but performed atomically on the server and logged, this also level permits forced push updates to branches. This level may allow existing commits to be discarded from a project history.

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.

Verified

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:

• -1 Fails

  Tried to compile, but got a compile error, or tried to run tests, but one or more tests did not pass.

  Any -1 blocks submit.

• 0 No score

  Didn't try to perform the verification tasks.

• +1 Verified

  Compiled (and ran tests) successfully.

  Any +1 enables submit.

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:

DELETE FROM approval_categories      WHERE category_id = 'VRIF';
DELETE FROM approval_category_values WHERE category_id = 'VRIF';

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.

Code Review

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:

• -2 Do not submit

  The code is so horribly incorrect/buggy/broken that it must not be submitted to this project, or to this branch.

  Any -2 blocks submit.

• -1 I would prefer that you didn't submit this

  The code doesn't look right, or could be done differently, but the reviewer is willing to live with it as-is if another reviewer accepts it, perhaps because it is better than what is currently in the project. Often this is also used by contributors who don't like the change, but also aren't responsible for the project long-term and thus don't have final say on change submission.

  Does not block submit.

• 0 No score

  Didn't try to perform the code review task, or glanced over it but don't have an informed opinion yet.

• +1 Looks good to me, but someone else must approve

  The code looks right to this reviewer, but the reviewer doesn't have access to the +2 value for this category. Often this is used by contributors to a project who were able to review the change and like what it is doing, but don't have final approval over what gets submitted.

• +2 Looks good to me, approved

  Basically the same as +1, but for those who have final say over how the project will develop.

  Any +2 enables submit.

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:

DELETE FROM approval_categories      WHERE category_id = 'CRVW';
DELETE FROM approval_category_values WHERE category_id = 'CRVW';

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.

Submit

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.

Your Category Here

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:

INSERT INTO approval_categories
  (name
  ,position
  ,function_name
  ,category_id)
VALUES
  ('Copyright Check'
  ,3
  'MaxWithBlock'
  ,'copy');

INSERT INTO approval_category_values
  (category_id,value,name)
VALUES
  ('copy', -1, 'Do not have copyright');

INSERT INTO approval_category_values
  (category_id,value,name)
VALUES
  ('copy', 0, 'No score');

INSERT INTO approval_category_values
  (category_id,value,name)
VALUES
  ('copy', 1, 'Copyright clear');

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.