diff options
Diffstat (limited to 'Documentation/access-control.txt')
| -rw-r--r-- | Documentation/access-control.txt | 1042 |
1 files changed, 756 insertions, 286 deletions
diff --git a/Documentation/access-control.txt b/Documentation/access-control.txt index 0984935b13..8d89fa2fe2 100644 --- a/Documentation/access-control.txt +++ b/Documentation/access-control.txt @@ -33,6 +33,7 @@ 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]] Anonymous Users ~~~~~~~~~~~~~~~ @@ -44,14 +45,47 @@ 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 +to grant `Read` access to this group as Gerrit requires an account identity for all other operations. +[[non-interactive_users]] +Non-Interactive Users +~~~~~~~~~~~~~~~~~~~~~ + +This is an internal user group, members of this group are not expected +to perform interactive operations on the Gerrit web frontend. + +However, sometimes such a user may need a separate thread pool in +order to prevent it from grabbing threads from the interactive users. + +These users live in a second thread pool, which separates operations +made by the non-interactive users from the ones made by the interactive +users. This ensures that the interactive users can keep working when +resources are tight. + +[[project_owners]] +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 +<<category_owner,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 +<<category_owner,project owners>> assigned on a parent project may +avoid the need to initially configure access rights for +newly created child projects. + +[[registered_users]] Registered Users ~~~~~~~~~~~~~~~~ All signed-in users are automatically a member of this group (and -also 'Anonymous Users', see above). +also <<anonymous_users,'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 @@ -64,22 +98,7 @@ 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. - -Project Owners -~~~~~~~~~~~~~~ - -Access rights assigned to this group are always evaluated within the -context of a project and are resolved to access rights for all users -which own the 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 projects owners assigned on a parent -project may avoid the need to initially configure access rights for -newly created child projects. +on any change in any project they have `Read` access to. Account Groups @@ -92,8 +111,8 @@ 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 to this group -* Remove users from this group +* 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 @@ -120,7 +139,7 @@ Project Access Control Lists ---------------------------- A system wide access control list affecting all projects is stored in -project "`\-- All Projects \--`". This inheritance can be configured +project "`All-Projects`". This inheritance can be configured through link:cmd-set-project-parent.html[gerrit set-project-parent]. Per-project access control lists are also supported. @@ -147,13 +166,13 @@ 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 +(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. 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 +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 link:http://www.brics.dk/automaton/[dk.brics.automaton library] @@ -164,7 +183,7 @@ particular regular expression flavor. References can have the current user name automatically included, creating dynamic access controls that change to match the currently logged in user. For example to provide a personal sandbox space -to all developers, `refs/heads/sandbox/$\{username\}/*` allowing +to all developers, `refs/heads/sandbox/${username}/*` allowing the user 'joe' to use 'refs/heads/sandbox/joe/foo'. When evaluating a reference-level access right, Gerrit will use @@ -175,12 +194,12 @@ the `refs/heads/qa` branch, and the following ACLs are granted on the project: [options="header"] -|===================================================== -|Group |Reference Name|Category |Range -|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 -|===================================================== +|=============================================================== +|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 | +|=============================================================== Then the effective range permitted to be used by the user is `-2..+2`, as the user's membership of `Foo Leads` effectively grant @@ -190,20 +209,21 @@ 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 prefixing -the reference specified with a `'-'`. +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: [options="header"] -|===================================================== -|Group |Reference Name|Category |Range -|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 -|===================================================== +|============================================================== +|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 +|============================================================== Then this user will not have `Code Review` rights on that change, since there is an exclusive access right in place for the @@ -216,14 +236,13 @@ In order to grant the ability to `Code Review` to the members of would be needed: [options="header"] -|===================================================== -|Group |Reference Name|Category |Range -|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 -|Foo Leads |refs/heads/qa |Code Review| -2..+2 -|===================================================== - +|============================================================== +|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 ~~~~~~~~~~~~~~~~~~~~~ @@ -237,249 +256,64 @@ in the `auth.trustedOpenID` list from `gerrit.config`. All Projects ~~~~~~~~~~~~ -Any access right granted to a group within `\-- 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 group `Administrators` may edit the access -control list for `\-- All Projects \--`. +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. +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 Access` category when granting `-1 No Access` -within a specific project to deny access to a group. +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. -Categories ----------- +[[access_category]] +Access 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 non-merge 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_READ_3]] -Upload Merge Access -~~~~~~~~~~~~~~~~~~~ -The `Read Access +3` permits the user to upload merge commits, but is -otherwise identical to `Read Access +2`. Some projects wish to -restrict merges to being created by Gerrit. By granting, -`Read Access +1..+2`, the only merges that enter the system will be -those created by Gerrit, or those pushed directly. - -[[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. +With the release of the Gerrit 2.2.x series, the web GUI for ACL +configuration was rewritten from scratch. Use this +<<conversion_table,table>> to better understand the access rights +conversions from the Gerrit 2.1.x to the Gerrit 2.2.x series. -* +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 -~~~~~~~~ +[[category_label-Verified]] +Label: 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 verified category is one of two default categories that is +configured upon the creation of a Gerrit instance. It may 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. +but one or more tests did not pass. This value is valid +across all patch sets in the same change, i.e. the reviewer must +actively change his/her review to something else before the change +is submittable. + *Any -1 blocks submit.* @@ -493,8 +327,8 @@ 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` +For a change to be submittable, 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. @@ -508,7 +342,7 @@ project, it can be deleted from the database: 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 +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 @@ -520,20 +354,25 @@ rows into the `approval_category_values` with `category_id` set to A restart is required after making database changes. See <<restart_changes,below>>. -[[category_CVRW]] -Code Review -~~~~~~~~~~~ +[[category_label-Code-Review]] +Label: 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 code review category is the second of two default categories that +is configured upon the creation of a Gerrit instance. It may 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. +submitted to this project, or to this branch. This value is valid +across all patch sets in the same change, i.e. the reviewer must +actively change his/her review to something else before the change +is submittable. + *Any -2 blocks submit.* @@ -568,10 +407,11 @@ 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. +For a change to be submittable, the latest patch set 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` on any patch set can block a submit, while `+2` on the +latest patch set can enable it. If a Gerrit installation does not wish to use this category in any project, it can be deleted from the database: @@ -583,7 +423,7 @@ project, it can be deleted from the database: 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 +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` @@ -604,7 +444,275 @@ have false-negatives that shouldn't block the change. A restart is required after making database changes. See <<restart_changes,below>>. -[[category_SUBM]] +[[category_create]] +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 previosuly 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. + +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. + + +[[category_forge_author]] +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. + + +[[category_forge_committer]] +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. + + +[[category_forge_server]] +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. + + +[[category_owner]] +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/`. See <<project_owners,project owners>> to find +out more about this role. + + +[[category_push]] +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. + + +[[category_push_direct]] +Direct Push +^^^^^^^^^^^ + +Any existing branch can be fast-forwarded to a new commit. +Creation of new branches is controlled by the +link:access-control.html#category_create['Create Reference'] +category. Deletion of existing branches is rejected. This is the +safest mode as commits cannot be discarded. + +* Force option ++ +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 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. + + +[[category_push_review]] +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 `Read` and `Push` for `refs/for/refs/heads/*` +to `Registered Users` in the `All-Projects` ACL. For more +private installations, its common to simply grant `Read` and +`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. + + +[[category_push_merge]] +Push Merge Commits +~~~~~~~~~~~~~~~~~~~~ + +The `Push Merge Commit` permits the user to upload merge commits. +It's an addon to the <<category_push,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. + + +[[category_push_annotated]] +Push Annotated 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. + +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 `Push Annotated Tag`. + +To push lightweight (non annotated) tags, grant +<<category_create,`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. + + +[[category_read]] +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. + +This category has a special behavior, where the per-project ACL is +evaluated before the global all projects ACL. If the per-project +ACL has granted `Read` with 'DENY', and does not otherwise grant +`Read` with 'ALLOW', then a `Read` in the all projects ACL +is ignored. This behavior is useful to hide a handful of projects +on an otherwise public server. + +For an open source, public Gerrit installation it is common to grant +`Read` to `Anonymous Users` in the `All-Projects` ACL, enabling +casual browsing of any project's changes, as well as fetching any +project's repository over SSH or HTTP. New projects can be +temporarily hidden from public view by granting `Read` with 'DENY' +to `Anonymous Users` and granting `Read` to the project owner's +group within the per-project ACL. + +For a private Gerrit installation using a trusted HTTP authentication +source, granting `Read` to `Registered Users` may be more +typical, enabling read access only to those users who have been +able to authenticate through the HTTP access controls. This may +be suitable in a corporate deployment if the HTTP access control +is already restricted to the correct set of users. + + +[[category_rebase]] +Rebase +~~~~~~ + +This category permits users to rebase changes via the web UI by pushing +the `Rebase Change` button. + +The change owner and submitters can always rebase changes in the web UI +(even without having the `Rebase` access right assigned). + +Users without this access right who are able to upload new patch sets +can still do the rebase locally and upload the rebased commit as a new +patch set. + + +[[category_submit]] Submit ~~~~~~ @@ -619,23 +727,22 @@ 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. +See above for descriptions of how <<category_verified,`Verified`>> +and <<category_review,`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. +meaning to Gerrit. The `position` column of `approval_categories` controls which column of the 'Approvals' table the category appears in, providing some @@ -665,7 +772,7 @@ like `Verified`, but has different names/labels: VALUES ('Copyright Check' ,3 - 'MaxWithBlock' + ,'MaxWithBlock' ,'copy'); INSERT INTO approval_category_values @@ -696,6 +803,369 @@ 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. + +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 guide lines for a typical way to set up your project on a +brand new Gerrit instance. + +[[examples_contributor]] +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: + +* <<category_read,`Read`>> on 'refs/heads/\*' and 'refs/tags/*' +* <<category_push,`Push`>> to 'refs/for/refs/heads/\*' and 'refs/changes/*' +* <<category_label-Code-Review,`Code review`>> with range '-1' to '+1' + + +[[examples_developer]] +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: + +* <<category_read,`Read`>> on 'refs/heads/\*' and 'refs/tags/*' +* <<category_push,`Push`>> to 'refs/for/refs/heads/\*' and 'refs/changes/*' +* <<category_push_merge,`Push merge commit`>> to 'refs/for/refs/heads/\*' and 'refs/changes/*' +* <<category_forge_author,`Forge Author Identity`>> +* <<category_label-Code-Review,`Label: Code review`>> with range '-2' to '+2' +* <<category_label-Verified,`Label: Verify`>> with range '-1' to '+1' +* <<category_submit,`Submit`>> + +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: + +* <<category_push,`Push`>> to 'refs/heads/*' +* <<category_push_merge,`Push merge commit`>> to 'refs/heads/*' + + +[[examples_cisystem]] +CI system +~~~~~~~~~ + +A typical Continous Integration system should be able to download new changes +to build and then leave a verdict somehow. + +As an example, the popular +link:https://wiki.jenkins-ci.org/display/JENKINS/Gerrit+Trigger[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 verify label. Depending on +the size of your project and discipline of involved developers you might want +to limit access right to the +1 `Verify` 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 +`Verify` label to -1. However that means that a failed build will block +submit of the change even if someone else sets `Verify` +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: + +* <<category_read,`Read`>> on 'refs/heads/\*' and 'refs/tags/*' +* <<category_label-Code-Review,`Label: Code review`>> with range '-1' to '0' +* <<category_label-Verified,`Label: Verify`>> with range '0' to '+1' + +Optional access rights to grant: + +* <<category_label-Code-Review,`Label: Code review`>> with range '-1' to '+1' +* <<category_push,`Push`>> to 'refs/for/refs/heads/\*' and 'refs/changes/*' + + +[[examples_integrator]] +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: + +* <<examples_developer,Developer rights>> +* <<category_push,`Push`>> to 'refs/heads/*' +* <<category_push_merge,`Push merge commit`>> to 'refs/heads/*' +* <<category_forge_committer,`Forge Committer Identity`>> to 'refs/for/refs/heads/\*' and 'refs/changes/*' +* <<category_create,`Create Reference`>> to 'refs/heads/*' +* <<category_push_annotated,`Push Annotated Tag`>> to 'refs/tags/*' + + +[[examples_project-owner]] +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 knowledgable 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: + +* <<examples_integrator,Integrator rights>> +* <<category_push,`Push`>> with the force option to 'refs/heads/\*' and 'refs/tags/*' + +Optional access right to grant: + +* <<category_owner,`Owner`>> in the gits they mostly work with. + +[[examples_administrator]] +Administrator +~~~~~~~~~~~~~ + +The administrator role is the most powerful role known in the Gerrit universe. +This role may grant itself (or others) any access right, and it already has +all capabilities granted as well. By default the +<<administrators,`Administrators` group>> is the group that has this role. + +Mandatory access rights: + +* <<capability_administrateServer,The `Administrate Server` capability>> + +Suggested access rights to grant: + +* <<examples_project-owner,Project owner rights>> + + +[[conversion_table]] +Conversion table from 2.1.x series to 2.2.x series +-------------------------------------------------- + +[options="header"] +|================================================================================= +|Gerrit 2.1.x |Gerrit 2.2.x +|Code review |<<category_label-Code-Review,Label: Code review>> +|Verify |<<category_label-Verified,Label: Verify>> +|Forge Identity +1 |Forge <<category_forge_author,author>> identity +|Forge Identity +2 |Forge <<category_forge_committer,committer>> & <<category_forge_author,author>> identity +|Forge Identity +3 |Forge <<category_forge_server,server>> & <<category_forge_committer,committer>> & <<category_forge_author,author>> identity +|Owner |<<category_owner,Owner>> +|Push branch +1 |<<category_push_direct,Push>> +|Push branch +2 |<<category_create,Create reference>> & <<category_push_direct,Push>> +|Push branch +3 |<<category_push_direct,Push>> (with force) & <<category_create,Create reference>> +|Push tag +1 & Push Branch +2 |No support to limit to push signed tag +|Push tag +2 & Push Branch +2 |<<category_push_annotated,Push annotated tag>> +|Push Branch +2 (refs/tags/*) |<<category_create,Create reference>> (refs/tags/...) +|Push Branch +3 (refs/tags/*) |<<category_push_direct,Push>> (with force on refs/tags/...) +|Read +1 |<<category_read,Read>> +|Read +2 |<<category_read,Read>> & <<category_push_review,Push>> (refs/for/refs/...) +|Read +3 |<<category_read,Read>> & <<category_push_review,Push>> (refs/for/refs/...) & <<category_push_merge,Push Merge Commit>> +|Submit |<<category_submit,Submit>> +|================================================================================= + + +[NOTE] +In Gerrit 2.2.x, the way to set permissions for upload has changed entirely. +To upload a change for review is no longer a separate permission type, +instead you grant ordinary push permissions to the actual +recieving reference. In practice this means that you set push permissions +on `refs/for/refs/heads/<branch>` rather than permissions to upload changes +on `refs/heads/<branch>`. + + +System capabilities +------------------- + +The system 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. + +Below you find a list of capabilities available: + + +[[capability_administrateServer]] +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. + + +[[capability_createAccount]] +Create Account +~~~~~~~~~~~~~~ + +Allow link:cmd-create-account.html[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 +link:access-control.html#non-interactive_users['Non-Interactive users'] group. + + +[[capability_createGroup]] +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 link:cmd-create-group.html[create new groups via ssh] or via the web UI. + + +[[capability_createProject]] +Create Project +~~~~~~~~~~~~~~ + +Allow project creation. This capability allows the granted group to +either link:cmd-create-project.html[create new git projects via ssh] +or via the web UI. + + +[[capability_flushCaches]] +Flush Caches +~~~~~~~~~~~~ + +Allow the flushing of Gerrit's caches. This capability allows the granted +group to link:cmd-flush-caches.html[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 <<capability_viewCaches,view caches capability>>. + + +[[capability_kill]] +Kill Task +~~~~~~~~~ + +Allow the operation of the link:cmd-kill.html[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 +recieve-pack. + + +[[capability_priority]] +Priority +~~~~~~~~ + +This capability allows users to use +link:config-gerrit.html#sshd.batchThreads[the thread pool reserved] for +link:access-control.html#non-interactive_users['Non-Interactive Users']. +It's a binary value in that granted users either have access to the thread +pool, or they don't. + +There are three modes for this capability and they're listed by rising +priority: + +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 'Non-Interactive 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. + + +[[capability_queryLimit]] +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 link:cmd-query.html[`gerrit query`] +command, but also to the web UI results pagination size. + + +[[capability_startReplication]] +Start Replication +~~~~~~~~~~~~~~~~~ + +Allow access to execute link:cmd-replicate.html[the `gerrit replicate` command]. + + +[[capability_viewCaches]] +View Caches +~~~~~~~~~~~ + +Allow querying for status of Gerrit's internal caches. This capability allows +the granted group to +link:cmd-show-caches.html[look at some or all Gerrit caches via ssh]. + + +[[capability_viewConnections]] +View Connections +~~~~~~~~~~~~~~~~ + +Allow querying for status of Gerrit's current client connections. This +capability allows the granted group to +link:cmd-show-connections.html[look at Gerrit's current connections via ssh]. + + +[[capability_viewQueue]] +View Queue +~~~~~~~~~~ + +Allow querying for status of Gerrit's internal task queue. This capability +allows the granted group to +link:cmd-show-queue.html[look at the Gerrit task queue via ssh]. + + GERRIT ------ Part of link:index.html[Gerrit Code Review] |