Access controls in Gerrit are group based. Every user account is a member of one or more groups, and access and privileges are granted to those groups. Access rights cannot be granted to individual users.

System Groups

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.

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

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.

Non-Interactive Users

This is an internal user group, members of this group are not expected to perform interactive operations on the Gerrit web frontend.

However, sometimes such a user may need a separate thread pool in order to prevent it from grabbing threads from the interactive users.

These users live in a second thread pool, which separates operations made by the non-interactive users from the ones made by the interactive users. This ensures that the interactive users can keep working when resources are tight.

Project Owners

Access rights assigned to this group are always evaluated within the context of a project to which the access rights apply. These rights therefore apply to all the users who are owners of this 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 project owners assigned on a parent project may avoid the need to initially configure access rights for newly created child projects.

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

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:

  • Add users and other groups to this group

  • Remove users and other groups 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.

Project Access Control Lists

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:

Group Reference Name Category Range

Anonymous Users

refs/heads/*

Code Review

-1..+1

Registered Users

refs/heads/*

Code Review

-1..+2

Foo Leads

refs/heads/*

Code Review

-2..0

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:

Group Reference Name Category Range Exclusive

Registered Users

refs/heads/*

Code Review

-1..+1

Foo Leads

refs/heads/*

Code Review

-2..+2

QA Leads

refs/heads/qa

Code Review

-2..+2

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 ticking the exclusive flag when setting the permission for the refs/heads/qa branch.

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:

Group Reference Name Category Range Exclusive

Registered Users

refs/heads/*

Code Review

-1..+1

Foo Leads

refs/heads/*

Code Review

-2..+2

QA Leads

refs/heads/qa

Code Review

-2..+2

X

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:

Group Reference Name Category Range Exclusive

Registered Users

refs/heads/*

Code Review

-1..+1

Foo Leads

refs/heads/*

Code Review

-2..+2

QA Leads

refs/heads/qa

Code Review

-2..+2

X

Foo Leads

refs/heads/qa

Code Review

-2..+2

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

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 groups with the Administrate Server capability may edit the access control list for All-Projects. By default this capability is given to the group Administrators, but can be given to more groups.

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 including global capabilities.

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 category when granting DENY within a specific project to deny a group access.

Access Categories

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

With the release of the Gerrit 2.2.x series, the web GUI for ACL configuration was rewritten from scratch. Use this table to better understand the access rights conversions from the Gerrit 2.1.x to the Gerrit 2.2.x series.

Label: Verified

The verified category is one of two default categories that is configured upon the creation of a Gerrit instance. It may 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. This value is valid across all patch sets in the same change, i.e. the reviewer must actively change his/her review to something else before the change is submittable.

    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.

For a change to be submittable, 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.

Note
A restart is required after making database changes. See below.

Label: Code Review

The code review category is the second of two default categories that is configured upon the creation of a Gerrit instance. It may 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. This value is valid across all patch sets in the same change, i.e. the reviewer must actively change his/her review to something else before the change is submittable.

    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.

For a change to be submittable, the latest patch set 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 on any patch set can block a submit, while +2 on the latest patch set 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.

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.

Note
A restart is required after making database changes. See below.

Abandon

This category controls whether users are allowed to abandon changes to projects in Gerrit. It can give permission to abandon a specific change to a given ref.

This also grants the permission to restore a change if the change can be uploaded.

Create reference

The create reference category controls whether it is possible to create new references, branches or tags. This implies that the reference must not already exist, it’s not a destructive permission in that you can’t overwrite or remove any previously existing references (and also discard any commits in the process).

It’s probably most common to either permit the creation of a single branch in many gits (by granting permission on a parent project), or to grant this permission to a name pattern of branches.

This permission is often given in conjunction with regular push branch permissions, allowing the holder of both to create new branches as well as bypass review for new commits on that branch.

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

For example, to grant the possibility to create new branches under the namespace foo, you have to grant this permission on refs/heads/foo/* for the group that should have it. Finally, if you plan to grant each user a personal namespace in where they are free to create as many branches as they wish, you should grant the create reference permission so it’s possible to create new branches. This is done by using the special ${username} keyword in the reference pattern, e.g. refs/heads/sandbox/${username}/*. If you do, it’s also recommended you grant the users the push force permission to be able to clean up stale branches.

Forge Author

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 parts of that validation, which may be necessary when mirroring changes from an upstream project.

Permits the use of an unverified author line in commit objects. This can be useful when applying patches received by email from 3rd parties, when cherry-picking changes written by others across branches, or when amending someone else’s commit to fix up a minor problem before submitting.

By default this is granted to Registered Users in all projects, but a site administrator may disable it if verified authorship is required.

Forge Committer

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 parts of that validation, which may be necessary when mirroring changes from an upstream project.

Allows the use of an unverified committer line in commit objects, or an unverified tagger line in annotated tag objects. Typically this is only required when mirroring commits from an upstream project repository.

Forge Server

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 parts of that validation, which may be necessary when mirroring changes from an upstream project.

Allows the use of the server’s own name and email on the committer line of a new commit object. This should only be necessary when force pushing a commit history which has been rewritten by git filter-branch and that contains merge commits previously created by this Gerrit Code Review server.

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.

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/. See project owners to find out more about this role.

Push

This category controls how users are allowed to upload new commits to projects in Gerrit. It can either give permission to push directly into a branch, bypassing any code review process that would otherwise be used. Or it may give permission to upload new changes for code review, this depends on which namespace the permission is granted to.

Direct Push

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

  • Force option

    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 option also permits forced push updates to branches. Enabling this option allows existing commits to be discarded from a project history.

The push 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.

Upload To Code Review

The Push access right granted on the namespace refs/for/refs/heads/BRANCH permits the user to upload a non-merge commit to the project’s refs/for/BRANCH namespace, creating a new change for code review.

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 the Read access granted to upload a change.

For an open source, public Gerrit installation, it is common to grant Read and Push for refs/for/refs/heads/* to Registered Users in the All-Projects ACL. For more private installations, its common to simply grant Read and Push for refs/for/refs/heads/* to all users of a project.

  • Force option

    The force option has no function when granted to a branch in the refs/for/refs/heads/* namespace.

Push Merge Commits

The Push Merge Commit access right permits the user to upload merge commits. It’s an addon to the Push access right, and so it won’t be sufficient with only Push Merge Commit granted for a push to happen. Some projects wish to restrict merges to being created by Gerrit. By granting Push without Push Merge Commit, the only merges that enter the system will be those created by Gerrit.

The reference name connected to a Push Merge Commit entry must always be prefixed with refs/for/, for example refs/for/refs/heads/BRANCH. This applies even for an entry that complements a Push entry for refs/heads/BRANCH that allows direct pushes of non-merge commits, and the intention of the Push Merge Commit entry is to allow direct pushes of merge commits.

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

It allows for a new annotated (unsigned) tag to be created. The tagger email address must be verified for the current user.

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

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

To delete or overwrite an existing tag, grant Push with the force option enabled for reference name refs/tags/*, as deleting a tag requires the same permission as deleting a branch.

Read

The Read category controls visibility to the project’s changes, comments, code diffs, and Git access over SSH or HTTP. A user must have this access granted 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 with DENY, and does not otherwise grant Read with ALLOW, then a Read 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 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 with DENY to Anonymous Users and granting Read to the project owner’s group within the per-project ACL.

For a private Gerrit installation using a trusted HTTP authentication source, granting Read 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.

Rebase

This category permits users to rebase changes via the web UI by pushing the Rebase Change button.

The change owner and submitters can always rebase changes in the web UI (even without having the Rebase access right assigned).

Users without this access right who are able to upload new patch sets can still do the rebase locally and upload the rebased commit as a new patch set.

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

Note
Restart the Gerrit web application and reload all browsers after making any database changes to approval categories. Browsers are sent the list of known categories when they first visit the site, and don’t notice changes until the page is closed and opened again, or is reloaded.

Examples of typical roles in a project

Below follows a set of typical roles on a server and which access rights these roles typically should be granted. You may see them as general guidelines for a typical way to set up your project on a brand new Gerrit instance.

Contributor

This is the typical user on a public server. They are able to read your project and upload new changes to it. They are able to give feedback on other changes as well, but are unable to block or approve any changes.

Suggested access rights to grant:

  • Read on refs/heads/* and refs/tags/*

  • Push to refs/for/refs/heads/* and refs/changes/*

  • Code review with range -1 to +1

Developer

This is the typical core developer on a public server. They are able to read the project, upload changes to a branch. They are allowed to push merge commits to merge branches together. Also, they are allowed to forge author identity, thus handling commits belonging to others than themselves, effectively allowing them to transfer commits between different branches.

They are furthermore able to code review and verify commits, and eventually submit them. If you have an automated CI system that builds all uploaded patch sets you might want to skip the verification rights for the developer and let the CI system do that exclusively.

Suggested access rights to grant:

If the project is small or the developers are seasoned it might make sense to give them the freedom to push commits directly to a branch.

Optional access rights to grant:

CI system

A typical Continous Integration system should be able to download new changes to build and then leave a verdict somehow.

As an example, the popular gerrit-trigger plugin for Jenkins/Hudson can set labels at:

  • The start of a build

  • A successful build

  • An unstable build (tests fails)

  • A failed build

Usually the range chosen for this verdict is the verify label. Depending on the size of your project and discipline of involved developers you might want to limit access right to the +1 Verify label to the CI system only. That way it’s guaranteed that submitted commits always get built and pass tests successfully.

If the build doesn’t complete successfully the CI system can set the Verify label to -1. However that means that a failed build will block submit of the change even if someone else sets Verify +1. Depending on the project and how much the CI system can be trusted for accurate results, a blocking label might not be feasible. A recommended alternative is to set the label Code-review to -1 instead, as it isn’t a blocking label but still shows a red label in the Gerrit UI. Optionally, to enable the possibility to deliver different results (build error vs unstable for instance), it’s also possible to set Code-review +1 as well.

If pushing new changes is granted, it’s possible to automate cherry-pick of submitted changes for upload to other branches under certain conditions. This is probably not the first step of what a project wants to automate however, and so the push right can be found under the optional section.

Suggested access rights to grant, that won’t block changes:

Optional access rights to grant:

Integrator

Integrators are like developers but with some additional rights granted due to their administrative role in a project. They can upload or push any commit with any committer email (not just their own) and they can also create new tags and branches.

Suggested access rights to grant:

Project owner

The project owner is almost like an integrator but with additional destructive power in the form of being able to delete branches. Optionally these users also have the power to configure access rights in gits assigned to them.

Warning
These users should be really knowledgable about git, for instance knowing why tags never should be removed from a server. This role is granted potentially destructive access rights and cleaning up after such a mishap could be time consuming!

Suggested access rights to grant:

Optional access right to grant:

  • Owner in the gits they mostly work with.

Administrator

The administrator role is the most powerful role known in the Gerrit universe. This role may grant itself (or others) any access right, and it already has all capabilities granted as well. By default the Administrators group is the group that has this role.

Mandatory access rights:

Suggested access rights to grant:

Conversion table from 2.1.x series to 2.2.x series

Gerrit 2.1.x Gerrit 2.2.x

Code review

Label: Code review

Verify

Label: Verify

Forge Identity +1

Forge author identity

Forge Identity +2

Forge committer & author identity

Forge Identity +3

Forge server & committer & author identity

Owner

Owner

Push branch +1

Push

Push branch +2

Create reference & Push

Push branch +3

Push (with force) & Create reference

Push tag +1 & Push Branch +2

No support to limit to push signed tag

Push tag +2 & Push Branch +2

Push annotated tag

Push Branch +2 (refs/tags/*)

Create reference (refs/tags/…)

Push Branch +3 (refs/tags/*)

Push (with force on refs/tags/…)

Read +1

Read

Read +2

Read & Push (refs/for/refs/…)

Read +3

Read & Push (refs/for/refs/…) & Push Merge Commit

Submit

Submit

Note
In Gerrit 2.2.x, the way to set permissions for upload has changed entirely. To upload a change for review is no longer a separate permission type, instead you grant ordinary push permissions to the actual recieving reference. In practice this means that you set push permissions on refs/for/refs/heads/<branch> rather than permissions to upload changes on refs/heads/<branch>.

System capabilities

The system capabilities control actions that the administrators of the server can perform which usually affect the entire server in some way. The administrators may delegate these capabilities to trusted groups of users.

Delegation of capabilities allows groups to be granted a subset of administrative capabilities without being given complete administrative control of the server. This makes it possible to keep fewer users in the administrators group, even while spreading much of the server administration burden out to more users.

Below you find a list of capabilities available:

Administrate Server

This is in effect the owner and administrator role of the Gerrit instance. Any members of a group granted this capability will be able to grant any access right to any group. They will also have all capabilities granted to them automatically.

Create Account

Allow account creation over the ssh prompt. This capability allows the granted group members to create non-interactive service accounts. These service accounts are generally used for automation and made to be members of the Non-Interactive users group.

Create Group

Allow group creation. Groups are used to grant users access to different actions in projects. This capability allows the granted group members to either create new groups via ssh or via the web UI.

Create Project

Allow project creation. This capability allows the granted group to either create new git projects via ssh or via the web UI.

Email Reviewers

Allow or deny sending email to change reviewers and watchers. This can be used to deny build bots from emailing reviewers and people who watch the change. Instead, only the authors of the change and those who starred it will be emailed. The allow rules are evaluated before deny rules, however the default is to allow emailing, if no explicit rule is matched.

Flush Caches

Allow the flushing of Gerrit’s caches. This capability allows the granted group to flush some or all Gerrit caches via ssh.

Note
This capability doesn’t imply permissions to the show-caches command. For that you need the view caches capability.

Kill Task

Allow the operation of the kill command over ssh. The kill command ends tasks that currently occupy the Gerrit server, usually a replication task or a user initiated task such as an upload-pack or recieve-pack.

Priority

This capability allows users to use the thread pool reserved for Non-Interactive Users. It’s a binary value in that granted users either have access to the thread pool, or they don’t.

There are three modes for this capability and they’re listed by rising priority:

No capability configured.

The user isn’t a member of a group with any priority capability granted. By default the user is then in the INTERACTIVE thread pool.

BATCH

If there’s a thread pool configured for Non-Interactive Users and a user is granted the priority capability with the BATCH mode selected, the user ends up in the separate batch user thread pool. This is true unless the user is also granted the below INTERACTIVE option.

INTERACTIVE

If a user is granted the priority capability with the INTERACTIVE option, regardless if they also have the BATCH option or not, they are in the INTERACTIVE thread pool.

Query Limit

Allow site administrators to configure the query limit for users to be above the default hard-coded value of 500. Administrators can add a global block to All-Projects with group(s) that should have different limits:

When applying a query limit to a user the largest value granted by any of their groups is used.

This limit applies not only to the gerrit query command, but also to the web UI results pagination size.

Start Replication

Allow access to execute replication start command, if the replication plugin is installed on the server.

View Caches

Allow querying for status of Gerrit’s internal caches. This capability allows the granted group to look at some or all Gerrit caches via ssh.

View Connections

Allow querying for status of Gerrit’s current client connections. This capability allows the granted group to look at Gerrit’s current connections via ssh.

View Queue

Allow querying for status of Gerrit’s internal task queue. This capability allows the granted group to look at the Gerrit task queue via ssh.


Part of Gerrit Code Review