gerrit/Documentation/access-control.txt

Gerrit Code Review - Access Controls
====================================

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.  Groups cannot be nested, and access rights cannot
be granted to individual users.


System Groups
-------------

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

Administrators
~~~~~~~~~~~~~~

This is the Gerrit "root" identity.

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

Membership in the 'Administrators' group does not imply any other
access rights.  Administrators do not automatically get code review
approval or submit rights in projects.  This is a feature designed
to permit 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.

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.

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

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

* Add users to this group
* Remove users from this group
* Change the name of this group
* Change the description of this group
* Change the owner of this group, to another group

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

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

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


Project Access Control Lists
----------------------------

A system wide access control list affecting all projects is stored
in project id 0 (named "`\-- All Projects \--`" in a default
installation).  Only the id is recognized as special by Gerrit.

Per-project access control lists are also supported.

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

[grid="all"]
`---------------`---------------`-------------`-------
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.

When evaluating a reference-level access right, Gerrit will use
the most specific set of access rights to determine if the user
is allowed to perform a given action. For example, if a user
tries to review a change destined for branch `refs/heads/qa`
in project `tools/gerrit`, and the following ACLs are granted:

[grid="all"]
`---------------`----------------`-------------`-------
Group            Reference Name  Category       Range
-------------------------------------------------------
Anonymous Users  refs/heads/*    Code Review     -1..+1
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 this user will have `Code Review -2..+2` if he is a member
of `QA Leads`, and will not have any rights if not. Inherited ACLs
from the `\-- All Projects \--` project thus allow system wide
lock-down of a branch, by granting a permission to a limited group
of users on that branch.

OpenID Authentication
~~~~~~~~~~~~~~~~~~~~~

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

All Projects
~~~~~~~~~~~~

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

Ownership of this project cannot be delegated to another group.

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

Per-Project
~~~~~~~~~~~

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


Categories
----------

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

[[category_OWN]]
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.

[[category_READ]]
Read Access
~~~~~~~~~~~

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

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

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

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

[[category_pTAG]]
Push 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.

The range of values is:

* +1 Create Signed Tag
+
A new signed tag may be created.  The tagger email address must be
verified for the current user.

* +2 Create Annotated Tag
+
A new annotated (unsigned) tag may be created.  The tagger email
address must be verified for the current user.

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

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

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

[[category_pHD]]
Push Branch
~~~~~~~~~~~

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

This category has several possible values:

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

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

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

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

[[category_FORG]]
Forge Identity
~~~~~~~~~~~~~~

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

* +1 Forge Author Identity
+
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.

* +2 Forge Committer or Tagger Identity
+
Implies 'Forge Author Identity', but also 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.

[[category_VRIF]]
Verified
~~~~~~~~

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

The range of values is:

* -1 Fails
+
Tried to compile, but got a compile error, or tried to run tests,
but one or more tests did not pass.
+
*Any -1 blocks submit.*

* 0 No score
+
Didn't try to perform the verification tasks.

* +1 Verified
+
Compiled (and ran tests) successfully.
+
*Any +1 enables submit.*

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

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

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

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

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

[NOTE]
A restart is required after making database changes.
See <<restart_changes,below>>.

[[category_CVRW]]
Code Review
~~~~~~~~~~~

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

The range of values is:

* -2 Do not submit
+
The code is so horribly incorrect/buggy/broken that it must not be
submitted to this project, or to this branch.
+
*Any -2 blocks submit.*

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

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

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

* +2 Looks good to me, approved
+
Basically the same as `+1`, but for those who have final say over
how the project will develop.
+
*Any +2 enables submit.*

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

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

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

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

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

[[function_MaxNoBlock]]
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 <<restart_changes,below>>.

[[category_SUBM]]
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.

[[category_makeoneup]]
Your Category Here
~~~~~~~~~~~~~~~~~~

Gerrit administrators can also make up their own categories.

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

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

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

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

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

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

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

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

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

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

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

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

[[restart_changes]]
[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.

GERRIT
------
Part of link:index.html[Gerrit Code Review]