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.
To view/edit the access controls for a specific project, first navigate to the projects page: for example, https://gerrit-review.googlesource.com/admin/repos/. Then click on the individual project, and then click Access. This will bring you to a url that looks like https://gerrit-review.googlesource.com/admin/repos/gerrit,access
System Groups
Gerrit comes with the following system groups:
-
Anonymous Users
-
Change Owner
-
Project Owners
-
Registered Users
The system groups are assigned special access and membership management privileges.
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.
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.
Change Owner
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.
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.
Predefined Groups
Predefined groups differs from system groups by the fact that they exist in NoteDb under refs/meta/group-names (like normal groups) but predefined groups are created on Gerrit site initialization and unique UUIDs are assigned to those groups. These UUIDs are different on different Gerrit sites.
Gerrit comes with two predefined groups:
-
Administrators
-
Service Users
Administrators
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.
Service Users
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 service users from the ones made by the interactive users. This ensures that the interactive users can keep working when resources are tight.
Before Gerrit 3.3, the 'Service Users' group was named 'Non-Interactive Users'.
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.
LDAP Groups
LDAP groups are Account Groups that are maintained inside of your LDAP instance. If you are using LDAP to manage your groups they will not appear in the Groups list. However you can use them just like regular Account Groups by prefixing your group with "ldap/" in the Access Control for a project. For example "ldap/foo-project" will add the LDAP "foo-project" group to the access list.
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.
When projects are set as parent projects, the child projects inherit all of the parent’s access rights. “All-Projects” is treated as a parent of all projects.
Per-project access control lists are also supported.
Users are permitted to use the maximum range granted to any of their
groups on a label. For example, a user is a member of Foo Leads
, and
the following ACLs are granted on a project:
Group | Reference Name | Label | 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 all of
refs/heads/master
, refs/heads/experimental
, refs/heads/release/1.0
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. One quirk is that the
shortest possible pattern expansion must be a valid ref name:
thus ^refs/heads/.*/name
will fail because refs/heads//name
is not a valid reference, but ^refs/heads/.+/name
will work.
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 | Label | 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 | Label | 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.
Special and magic references
The reference namespaces used in git are generally two, one for branches and one for tags:
-
refs/heads/*
-
refs/tags/*
However, every reference under refs/* is really available, and in Gerrit this opportunity for giving other refs a special meaning is used. In Gerrit they are sometimes used as magic/virtual references that give the push to Gerrit a special meaning.
Special references
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.
refs/changes/*
Under this namespace each uploaded patch set for every change gets a static reference in their git. The format is convenient but still intended to scale to hundreds of thousands of patch sets. To access a given patch set you will need the change number and patch set number.
'refs/changes/'<last two digits of change number>/ <change number>/ <patch set number>
You can also find these static references linked on the page of each change.
refs/meta/config
This is where the Gerrit configuration of each project resides. This branch contains several files of importance: project.config, groups and rules.pl. Together they control access and behavior during the change review process.
refs/meta/dashboards/*
There’s a dedicated page where you can read more about User Dashboards.
refs/notes/review
Autogenerated copy of review notes for all changes in the git. Each log entry on the refs/notes/review branch also references the patch set on which the review is made. This functionality is provided by the review-notes plugin.
Magic references
These are references with added functionality to them compared to a regular git push operation.
refs/for/<branch ref>
Most prominent is the refs/for/<branch ref>
reference which is the reference
upon which we build the code review intercept before submitting a commit to
the branch it’s uploaded to.
Further documentation on how to push can be found on the Upload changes page.
Access Categories
Gerrit has several permission categories that can be granted to groups within projects, enabling functionality for that group’s members.
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.
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.
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. 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.
If auth.userNameCaseInsensitive
is enabled, the ${username}
is still case sensitive and will use
the capitalization used during account creation. This is done, since
git branches are case sensitive, so that sandbox branches containing
${username}
are still reachable by the users.
Delete Reference
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.
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
-
Grant/revoke any access rights, including
Owner
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).
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
Implies Delete Reference. 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
Push
for refs/for/refs/heads/*
to Registered Users
in the
All-Projects
ACL. For more private installations, its common to
grant 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.
Add Patch Set
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.
Push Merge Commits
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.
Create Annotated Tag
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:
git push ssh://USER@HOST:PORT/PROJECT tag v1.0
Or:
git push https://HOST/PROJECT tag v1.0
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/*
.
Create Signed Tag
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:
git push ssh://USER@HOST:PORT/PROJECT tag v1.0
Or:
git push https://HOST/PROJECT tag v1.0
Tags must be signed (created with git tag -s
), should exist in the
refs/tags/
namespace, and should be new.
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.
Special behaviors
This category has multiple special behaviors:
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.
You cannot grant Read
on the refs/tags/
namespace. Visibility to
refs/tags/
is derived from Read
grants on refs namespaces other than
refs/tags/
, refs/changes/
, and refs/cache-automerge/
by finding
tags reachable from those refs. For example, if a tag refs/tags/test
points to a commit on the branch refs/heads/master
, then allowing
Read
access to refs/heads/master
would also allow access to
refs/tags/test
. If a tag is reachable from multiple refs, allowing
access to any of those refs allows access to the tag.
Typical usage
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
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.
Revert
This category permits users to revert changes via the web UI by pushing
the Revert Change
button.
Users without this access right who are able to upload changes can still do the revert locally and upload the revert commit as a new change.
Remove Label (Remove Vote)
For every configured label My-Name
in the project, there is a
corresponding permission removeLabel-My-Name
with a range corresponding to
the defined values. For these values, the users are permitted to remove
other users' votes from a change.
Change owners can always remove zero or positive votes (even without
having the Remove Vote
access right assigned).
Project owners and site administrators can always remove any vote (even
without having the Remove Vote
access right assigned).
Users without this access right can still remove their own votes.
Remove Reviewer
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.
Review Labels
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.
Submit
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.
Submit (On Behalf Of)
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.
View Private Changes
This category permits users to view all private changes and all change edit refs.
The change owner and any explicitly added reviewers can always see
private changes (even without having the View Private Changes
access
right assigned).
NOTE: If
auth.skipFullRefEvaluationIfAllRefsAreVisible is true
(which is the case by
default) privates changes and all change edit refs are also visible to users
that have read access on refs/*
.
Toggle Work In Progress state
This category controls who is able to flip the Work In Progress bit.
Change owner, server administrators and project owners can always flip
the Work In Progress bit of the change (even without having the
Toggle Work In Progress state
access right assigned).
Must be assigned on the target branch ref (i.e. on 'refs/heads/', not on 'refs/for/').
Delete Own Changes
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.
Delete Changes
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.
Edit Topic Name
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.
Edit Hashtags
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).
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/\*' -
Push
to 'refs/for/refs/heads/*' -
Code-Review
with range '-1' to '+1' for 'refs/heads/*'
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.
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:
-
Read
on 'refs/heads/\*' -
Push
to 'refs/for/refs/heads/*' -
Push merge commit
to 'refs/for/refs/heads/*' -
Forge Author Identity
to 'refs/heads/*' -
Label: Code-Review
with range '-2' to '+2' for 'refs/heads/*' -
Label: Verified
with range '-1' to '+1' for 'refs/heads/*' -
Submit
on 'refs/heads/*'
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:
-
Push
to 'refs/heads/*' -
Push merge commit
to 'refs/heads/*'
CI system
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:
-
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 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:
-
Read
on 'refs/heads/\*' -
Label: Code-Review
with range '-1' to '0' for 'refs/heads/*' -
Label: Verified
with range '0' to '+1' for 'refs/heads/*'
Optional access rights to grant:
-
Label: Code-Review
with range '-1' to '+1' for 'refs/heads/*' -
Push
to 'refs/for/refs/heads/*'
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:
-
Push
to 'refs/heads/*' -
Push merge commit
to 'refs/heads/*' -
Forge Committer Identity
to 'refs/for/refs/heads/*' -
Create Reference
to 'refs/heads/*' -
Create Annotated Tag
to 'refs/tags/*'
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 knowledgeable 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:
-
Push
with the force option to 'refs/heads/*' and 'refs/tags/*'
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. By default the
Administrators
group is the group that has this role.
Mandatory access rights:
Suggested access rights to grant:
-
Any
capabilities
needed by the administrator
Enforcing site wide access policies
By granting the Owner
access right on the refs/*
to a
group, Gerrit administrators can delegate the responsibility of maintaining
access rights for that project to that group.
In a corporate deployment it is often necessary to enforce some access policies. An example could be that no-one can update or delete a tag, not even the project owners. The 'ALLOW' and 'DENY' rules are not enough for this purpose as project owners can grant themselves any access right they wish and, thus, effectively override any inherited access rights from the “All-Projects” or some other common parent project.
What is needed is a mechanism to block a permission in a parent project so that even project owners cannot allow a blocked permission in their child project. Still, project owners should retain the possibility to manage all non-blocked rules as they wish. This gives best of both worlds:
-
Gerrit administrators can concentrate on enforcing site wide policies and providing a meaningful set of default access permissions
-
Project owners can manage access rights of their projects without a danger of violating a site wide policy
'BLOCK' access rule
The 'BLOCK' rule can be used to take away rights from users. The BLOCK rule works across project inheritance, from the top down, so an administrator can use 'BLOCK' rules to enforce site-wide restrictions.
For example, if a user in the 'Foo Users' group tries to push to 'refs/heads/master' with the permissions below, that user will be blocked
Project | Inherits From | Reference Name | Permissions | |
---|---|---|---|---|
All-Projects |
- |
refs/* |
push = block Foo Users |
|
Foo |
All-Projects |
refs/heads/* |
push = Foo Users |
'BLOCK' rules are evaluated starting from the parent project, and after a 'BLOCK' rule is found to apply, further rules are ignored. Hence, in this example, the permissions on child-project is ignored.
All-Projects: project.config [access "refs/heads/*"] push = block group X child-project: project.config [access "refs/heads/*"] exclusiveGroupPermissions = push push = group X
In this case push for group 'X' will be blocked, even though the Exclusive flag was set for the child-project.
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:
[access "refs/heads/*"] label-Code-Review = block -2..+2 group X
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.
'BLOCK' and 'ALLOW' rules in the same access section
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:
[access "refs/heads/*"] push = block group X push = group Y
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'.
'BLOCK' and 'ALLOW' rules in the same project with the Exclusive flag
When a project contains a 'BLOCK' and 'ALLOW' that uses the Exclusive flag in a more specific reference, the 'ALLOW' rule with the Exclusive flag will override the 'BLOCK' rule:
[access "refs/*"] read = block group X [access "refs/heads/*"] exclusiveGroupPermissions = read read = group X
In this case a user which is a member of the group 'X' will still be allowed to read 'refs/heads/*'.
Note
|
An 'ALLOW' rule overrides a 'BLOCK' rule only when both of them are inside the same access section of the same project. An 'ALLOW' rule in a different access section of the same project or in any access section in an inheriting project cannot override a 'BLOCK' rule. |
Examples
The following examples show some possible use cases for the 'BLOCK' rules.
Make sure no one can update or delete a tag
This requirement is quite common in a corporate deployment where reproducibility of a build must be guaranteed. To achieve that we block 'push' permission for the 'Anonymous Users' in “All-Projects”:
[access "refs/tags/*"] push = block group Anonymous Users
By blocking the 'Anonymous Users' we effectively block everyone as everyone is a member of that group. Note that the permission to create a tag is still necessary. Assuming that only project owners are allowed to create tags, we would extend the example above:
[access "refs/tags/*"] push = block group Anonymous Users create = group Project Owners pushTag = group Project Owners
Let only a dedicated group vote in a special category
Assume there is a more restrictive process for submitting changes in stable release branches which is manifested as a new voting category 'Release-Process'. Assume we want to make sure that only a 'Release Engineers' group can vote in this category and that even project owners cannot approve this category. We have to block everyone except the 'Release Engineers' to vote in this category and, of course, allow 'Release Engineers' to vote in that category. In the “All-Projects” we define the following rules:
[access "refs/heads/stable*"] label-Release-Process = block -1..+1 group Anonymous Users label-Release-Process = -1..+1 group Release Engineers
Global Capabilities
The global 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.
Global capabilities are assigned to groups in the access rights settings of the root project (“All-Projects”).
Below you find a list of capabilities available:
Access Database
Allow users to view code review metadata refs in repositories.
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.
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.
Batch Changes Limit
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.
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 'Service 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 by navigating at the top of the page to BROWSE → Groups, and then pushing the "CREATE NEW" button.
Create Project
Allow project creation.
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 receive-pack.
Maintain Server
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:
Modify Account
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 allows to view secondary emails of other accounts.
Priority
This capability allows users to use the thread pool reserved for 'Service 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 'Service 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.
Read As
Allow users to impersonate any user to see which refs they can read.
Run As
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.
Run Garbage Collection
Allow users to run the Git garbage collection for the repositories of all projects.
Stream Events
Allow performing streaming of Gerrit events. This capability allows the granted group to stream Gerrit events via ssh.
View Access
Allow checking access rights for arbitrary (user, project) pairs, using the check.access endpoint
View All Accounts
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 View Secondary Emails capability or the Modify Account capability.
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 Plugins
Allow viewing the list of installed plugins.
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.
View Secondary Emails
Allows viewing secondary emails of other accounts.
Users with the Modify Account capability have this capbility implicitly.
Permission evaluation reference
Permission evaluation is expressed in the following concepts:
-
PermisssionRule: a single combination of {ALLOW, DENY, BLOCK} and group, and optionally a vote range and an 'exclusive' bit.
-
Permission: groups PermissionRule by permission name. All PermissionRules for same access type (eg. "read", "push") are grouped into a Permission implicitly. The exclusive bit lives here.
-
AccessSection: ties a list of Permissions to a single ref pattern. Each AccessSection comes from a single project.
Here is how these play out in a project.config file:
# An AccessSection [access "refs/heads/stable/*"] exclusiveGroupPermissions = create # Each of the following lines corresponds to a PermissionRule # The next two PermissionRule together form the "read" Permission read = group Administrators read = group Registered Users # A Permission with a block and block-override create = block group Registered Users create = group Project Owners # A Permission and PermissionRule for a label label-Code-Review = -2..+2 group Project Owners
Ref permissions
Access to refs can be blocked, allowed or denied.
BLOCK
For blocking access, all rules marked BLOCK are tested, and if one such rule matches, the user is denied access.
The rules are ordered by inheritance, starting from All-Projects down. Within a project, more specific ref patterns come first. The downward ordering lets administrators enforce access rules across all projects in a site.
BLOCK rules can have exceptions defined on the same project (eg. BLOCK anonymous users, ie. everyone, but make an exception for Admin users), either by:
-
adding ALLOW PermissionRules in the same Permission. This implies they apply to the same ref pattern.
-
adding an ALLOW Permission in the same project with a more specific ref pattern, but marked "exclusive". This allows them to apply to different ref patterns.
Such additions not only bypass BLOCK rules, but they will also grant permissions when they are processed in the ALLOW/DENY processing, as described in the next subsection.
ALLOW
For allowing access, all ALLOW/DENY rules that might apply to a ref are tested until one granting access is found, or until either an "exclusive" rule ends the search, or all rules have been tested.
The rules are ordered from specific ref patterns to general patterns, and for equally specific patterns, from originating project up to All-Projects.
This ordering lets project owners apply permissions specific to their project, overwriting the site defaults specified in All-Projects.
DENY
DENY is processed together with ALLOW.
As said, during ALLOW/DENY processing, rules are tried out one by one. For each (permission, ref-pattern, group) only a single rule ALLOW/DENY rule is picked. If that first rule is a DENY rule, any following ALLOW rules for the same (permission, ref-pattern, group) will be ignored, canceling out their effect.
DENY is confusing because it only works on a specific (ref-pattern, group) pair. The parent project can undo the effect of a DENY rule by introducing an extra rule which features a more general ref pattern or a different group.
DENY/ALLOW example
Consider the ref "refs/a" and the following configuration:
child-project: project.config [access "refs/a"] read = deny group A All-Projects: project.config [access "refs/a"] read = group A # ALLOW [access "refs/*"] read = group B # ALLOW
When determining access, first "read = DENY group A" on "refs/a" is encountered. The following rule to consider is "ALLOW read group A" on "refs/a". The latter rule applies to the same (permission, ref-pattern, group) tuple, so it it is ignored.
The DENY rule does not affect the last rule for "refs/*", since that has a different ref pattern and a different group. If group B is a superset of group A, the last rule will still grant group A access to "refs/a".
Double use of exclusive
An 'exclusive' permission is evaluated both during BLOCK processing and during ALLOW/DENY: when looking BLOCK, 'exclusive' stops the search downward, while the same permission in the ALLOW/DENY processing will stop looking upward for further rule matches
Force permission
The 'force' setting may be set on ALLOW and BLOCK rules. In the case of ALLOW, the 'force' option makes the permission stronger (allowing both forced and unforced actions). For BLOCK, the 'force' option makes it weaker (the BLOCK with 'force' only blocks forced actions).
Labels
Labels use the same mechanism, with the following observations:
-
The 'force' setting has no effect on label ranges.
-
BLOCK specifies the values that a group cannot vote, eg.
label-Code-Review = block -2..+2 group Anonymous Users
prevents all users from voting -2 or +2.
-
DENY works for votes too, with the same caveats
-
The blocked vote range is the union of the all the blocked vote ranges across projects, so in
All-Projects: project.config label-Code-Review = block -2..+1 group A Child-Project: project-config label-Code-Review = block -1..+2 group A
members of group A cannot vote at all in the Child-Project.
-
The allowed vote range is the union of vote ranges allowed by all of the ALLOW rules. For example, in
label-Code-Review = -2..+1 group A label-Code-Review = -1..+2 group B
a user that is both in A and B can vote -2..2.
Part of Gerrit Code Review