Access control documentation: Reordering categories Access categories are now sorted to match drop down box in UI This commit is made to prepare for the rewrite of categories in accordance with how they work in the Gerrit 2.2.x series. Change-Id: I7229335f86ce24ec1fceecaea71e3fa1158f15ca
diff --git a/Documentation/access-control.txt b/Documentation/access-control.txt index 42a6eae..4f45eb9 100644 --- a/Documentation/access-control.txt +++ b/Documentation/access-control.txt
@@ -279,204 +279,6 @@ 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. - -* +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 ~~~~~~~~ @@ -615,6 +417,204 @@ A restart is required after making database changes. See <<restart_changes,below>>. +[[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_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_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_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_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_SUBM]] Submit ~~~~~~