Gerrit Code Review - Access Controls

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.

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.

Access rights assigned to this group are always evaluated within the context of a change to which the access rights apply. These rights therefore apply to the user who is the owner of this change.

It is typical to assign a label to this group, allowing the change owner to vote on his change, but not actually cause it to become approved or rejected.

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.

This is a predefined group, created on Gerrit site initialization, that has the capability 'Administrate Server' assigned.

It is a normal Gerrit group without magic. This means if you remove the 'Administrate Server' capability from it, its members are no longer Gerrit administrators, despite the group name. The group may also be renamed.

This is the Gerrit "batch" identity. The capabilities 'Priority BATCH' and 'Stream Events' are assigned to this predefined group on Gerrit site creation.

The members of this group are not expected to perform interactive operations on the Gerrit web front-end.

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.

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

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.

The special references have content that’s either generated by Gerrit or contains important project configuration that Gerrit needs. When making changes to these references, Gerrit will take extra precautions to verify the contents compatibility at upload time.

These are references with added functionality to them compared to a regular git push operation.

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.

The uploader of a change, anyone granted the Owner permission at the ref or project level, and anyone granted the Administrate Server permission can also Abandon changes.

This also grants the permission to restore a change if the user also has push permission on the change’s destination ref.

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. To push a lightweight tag on a new commit (commit not reachable from any branch/tag) grant Push permission on refs/tags/* too. The Push permission on refs/tags/* also allows fast-forwarding of lightweight tags.

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.

The delete reference category controls whether it is possible to delete references, branches or tags. It doesn’t allow any other update of references.

Deletion of references is also possible if Push with the force option is granted, however that includes the permission to fast-forward and force-update references to existing and new commits. Being able to push references for new commits is bad if bypassing of code review must be prevented.

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.

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.

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.

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

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.

For the All-Projects root project any Owner access right on 'refs/*' is ignored since this permission would allow users to edit the global capabilities, which is the same as being able to administrate the Gerrit server (e.g. the user could assign the Administrate Server capability to the own account).

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.

This category controls which users are allowed to upload new patch sets to existing changes. Irrespective of this permission, change owners are always allowed to upload new patch sets for their changes. This permission needs to be set on refs/for/*.

By default, this permission is granted to Registered Users on refs/for/*, allowing all registered users to upload a new patch set to any change. Revoking this permission (by granting it to no groups and setting the "Exclusive" flag) will prevent users from uploading a patch set to a change they do not own.

The Push Merge Commit access right permits the user to upload merge commits. It’s an add-on 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.

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

Or:

Tags must be annotated (created with git tag -a), 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 Create 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.

To push an annotated tag on a new commit (commit not reachable from any branch/tag) grant Push permission on refs/tags/* too. The Push permission on refs/tags/* does not allow updating of annotated tags, not even fast-forwarding of annotated tags. Update of annotated tags is only allowed by granting Push with force option on refs/tags/*.

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

Or:

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

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.

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.

This category permits users to remove other users from the list of reviewers on a change.

Change owners can always remove reviewers who have given a zero or positive score (even without having the Remove Reviewer access right assigned).

Project owners and site administrators can always remove any reviewer (even without having the Remove Reviewer access right assigned).

Users without this access right can only remove themselves from the reviewer list on a change.

For every configured label My-Name in the project, there is a corresponding permission label-My-Name with a range corresponding to the defined values. There is also a corresponding labelAs-My-Name permission that enables editing another user’s label.

Gerrit comes pre-configured with a default 'Code-Review' label that can be granted to groups within projects, enabling functionality for that group’s members. Custom labels may also be defined globally or on a per-project basis.

This category permits users to submit changes.

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 labels (such as Verified and Code-Review, above) must enable submit, and also must not block it. See above for details on each label.

To immediately submit a change on push the caller needs to have the Submit permission on refs/for/<ref> (e.g. on refs/for/refs/heads/master).

Submitting to the refs/meta/config branch is only allowed to project owners. Any explicit submit permissions for non-project-owners on this branch are ignored. By submitting to the refs/meta/config branch the configuration of the project is changed, which can include changes to the access rights of the project. Allowing this to be done by a non-project-owner would open a security hole enabling editing of access rights, and thus granting of powers beyond submitting to the configuration.

This category permits users who have also been granted the Submit permission to submit changes on behalf of another user, by using the on_behalf_of field in SubmitInput when submitting using the REST API.

Note that this permission is named submitAs in the project.config file.

This category permits users to view all private changes.

The change owner and any explicitly added reviewers can always see private changes (even without having the View Private Changes access right assigned).

This category permits users to delete their own changes if they are not merged yet. This means only own changes that are open or abandoned can be deleted.

This category permits users to delete other users' changes if they are not merged yet. This means only changes that are open or abandoned can be deleted.

Having this permission implies having the Delete Own Changes permission.

Administrators may always delete changes without having this permission.

This category permits users to edit the topic name of a change that is uploaded for review.

The change owner, branch owners, project owners, and site administrators can always edit the topic name (even without having the Edit Topic Name access right assigned).

Whether the topic can be edited on closed changes can be controlled by the 'Force Edit' flag. If this flag is not set the topic can only be edited on open changes.

This category permits users to add or remove hashtags on a change that is uploaded for review.

The change owner, branch owners, project owners, and site administrators can always edit or remove hashtags (even without having the Edit Hashtags access right assigned).

This category permits users to set who is assigned to a change that is uploaded for review.

The change owner, ref owners, and the user currently assigned to a change can always change the assignee.

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:

If it’s desired to have the possibility to upload temporarily hidden changes there’s a specific permission for that. This enables someone to add specific reviewers for early feedback before making the change publicly visible.

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:

A typical Continuous 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:

Usually the range chosen for this verdict is the Verified label. Depending on the size of your project and discipline of involved developers you might want to limit access right to the +1 Verified 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 Verified label to -1. However that means that a failed build will block submit of the change even if someone else sets Verified +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:

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:

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.

Suggested access rights to grant:

Optional access right to grant:

The administrator role is the most powerful role known in the Gerrit universe. This role may grant itself (or others) any access right. By default the Administrators group is the group that has this role.

Mandatory access rights:

Suggested access rights to grant:

The 'BLOCK' rule blocks a permission globally. An inherited 'BLOCK' rule cannot be overridden in the inheriting project. Any 'ALLOW' rule from an inheriting project, which conflicts with an inherited 'BLOCK' rule will not be honored. Searching for 'BLOCK' rules, in the chain of parent projects, ignores the Exclusive flag, unless the rule with the Exclusive flag is defined on the same project as the 'BLOCK' rule. This means within the same project a 'BLOCK' rule can be overruled by 'ALLOW' rules on the same access section and 'ALLOW' rules with Exclusive flag on access section for more specific refs.

A 'BLOCK' rule that blocks the 'push' permission blocks any type of push, force or not. A blocking force push rule blocks only force pushes, but allows non-forced pushes if an 'ALLOW' rule would have permitted it.

It is also possible to block label ranges. To block a group 'X' from voting '-2' and '+2', but keep their existing voting permissions for the '-1..+1' range intact we would define:

The interpretation of the 'min..max' range in case of a blocking rule is: block every vote from '-INFINITE..min' and 'max..INFINITE'. For the example above it means that the range '-1..+1' is not affected by this block.

When an access section of a project contains a 'BLOCK' and an 'ALLOW' rule for the same permission then this 'ALLOW' rule overrides the 'BLOCK' rule:

In this case a user which is a member of the group 'Y' will still be allowed to push to 'refs/heads/*' even if it is a member of the group 'X'.

The following examples show some possible use cases for the 'BLOCK' rules.

Allow users to access the database using the gsql command, and view code review metadata refs in repositories.

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.

In most installations only those users who have direct filesystem and database access should be granted this capability.

This capability does not imply any other access rights. Users that have this capability 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.

Allow site administrators to configure the batch changes limit for users to override the system config 'receive.maxBatchChanges'.

Administrators can add a global block to All-Projects with group(s) that should have different limits.

When applying a batch changes limit to a user the largest value granted by any of their groups is used. 0 means no limit.

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.

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.

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

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.

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

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

Allow basic, constrained server maintenance tasks, such as flushing caches and reindexing changes. Does not grant arbitrary database access, read/write, or ACL management permissions, as might the administrate server capability.

Implies the following capabilities:

Allow to modify accounts over the ssh prompt. This capability allows the granted group members to modify any user account setting. In addition this capability is required to view secondary emails of other accounts.

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:

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.

Allow users to impersonate any user to see which refs they can read.

Allow users to impersonate any other user with the X-Gerrit-RunAs HTTP header on REST API calls, or the suexec SSH command.

When impersonating an administrator the Administrate Server capability is not honored. This security feature tries to prevent a role with Run As capability from modifying the access controls in All-Projects, however modification may still be possible if the impersonated user has permission to push or submit changes on refs/meta/config. Run As also blocks using most capabilities including Create User, Run Garbage Collection, etc., unless the capability is also explicitly granted to a group the administrator is a member of.

Administrators do not automatically inherit this capability; it must be explicitly granted.

Allow users to run the Git garbage collection for the repositories of all projects.

Allow performing streaming of Gerrit events. This capability allows the granted group to stream Gerrit events via ssh.

Allow checking access rights for arbitrary (user, project) pairs, using the check.access endpoint

Allow viewing all accounts for purposes of auto-completion, regardless of accounts.visibility setting.

This capability allows to view all accounts but not all account data. E.g. secondary emails of all accounts can only be viewed with the Modify Account capability.

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.

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.

Allow viewing the list of installed plugins.

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.

Access to refs can be blocked, allowed or denied.

Labels use the same mechanism, with the following observations:

Part of Gerrit Code Review