| 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. |
| |
| 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/`. |
| |
| [[category_READ]] |
| Read Access |
| ~~~~~~~~~~~ |
| |
| The `Read Access` category controls visibility to the project's |
| changes, comments, code diffs, and Git access over SSH or HTTP. |
| A user must have `Read Access +1` in order to see a project, its |
| changes, or any of its data. |
| |
| This category has a special behavior, where the per-project ACL is |
| evaluated before the global all projects ACL. If the per-project |
| ACL has granted `Read 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 or HTTP. |
| 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_READ_2]] |
| Upload Access |
| ~~~~~~~~~~~~~ |
| |
| The `Read Access +2` permits the user to upload a commit to the |
| project's `refs/for/BRANCH` namespace, creating a new change for |
| code review. |
| |
| Rather than place this permission in its own category, its chained |
| into the Read Access category as a higher level of access. 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 |
| Read Access +1 to even develop a change. Therefore upload access |
| implies read access by simply being a higher level of it. |
| |
| For an open source, public Gerrit installation, it is common to |
| grant `Read Access +1..+2` to `Registered Users` in the `\-- All |
| Projects \--` ACL. For more private installations, its common to |
| simply grant `Read Access +1..+2` to all users of a project. |
| |
| [[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. |
| |
| * +3 Forge Gerrit Code Review Server Identity |
| + |
| Implies 'Forge Committer or Tagger Identity' as well as 'Forge |
| Author Identity', but additionally 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. |
| |
| [[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] |