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