opendev/gerrit
Code Issues Proposed changes

Access control documentation: Owner and Push

Browse Source 
Owner category has it's link changed.

Push category takes a lot of rewrite, since the +2 Read access is
actually a tweak of push (to a different namespace) now. This impacts
many error messages and other references in the documentation.

Change-Id: I2a422ace35454b2dbb15ab93aa1243804e0e4b78
Signed-off-by: Fredrik Luthander <fredrik.luthander@sonyericsson.com>
This commit is contained in:
Fredrik Luthander
2011-12-29 11:36:48 +01:00
committed by Gustaf Lundh
parent 8f430f1207
commit ea13ca5761
4 changed files with 63 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

91
Documentation/access-control.txt
View File

@@ -84,10 +84,10 @@ therefore apply to all the users who are owners of this project.
By assigning access rights to this group on a parent project Gerrit By assigning access rights to this group on a parent project Gerrit
administrators can define a set of default access rights for administrators can define a set of default access rights for
<<category_OWN,project owners>>. Child projects inherit these <<category_owner,project owners>>. Child projects inherit these
access rights where they are resolved to the users that own the child access rights where they are resolved to the users that own the child
project. Having default access rights for project. Having default access rights for
<<category_OWN,project owners>> assigned on a parent project may <<category_owner,project owners>> assigned on a parent project may
avoid the need to initially configure access rights for avoid the need to initially configure access rights for
newly created child projects. newly created child projects.
@@ -543,7 +543,8 @@ pushing a commit history which has been rewritten by 'git filter-branch'
and that contains merge commits previously created by this Gerrit Code and that contains merge commits previously created by this Gerrit Code
Review server. Review server.
[[category_OWN]]
[[category_owner]]
Owner Owner
~~~~~ ~~~~~
@@ -568,60 +569,66 @@ further refine access, but only for references that begin with
out more about this role. out more about this role.
[[category_pHD]] [[category_push]]
Push Branch Push
~~~~~~~~~~~ ~~~~
This category permits users to push directly into a branch over SSH, This category controls how users are allowed to upload new commits
bypassing any code review process that would otherwise be used. 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.
This category has several possible values:
* +1 Update Branch [[category_push_direct]]
+ Direct Push
^^^^^^^^^^^
Any existing branch can be fast-forwarded to a new commit. Any existing branch can be fast-forwarded to a new commit.
Creation of new branches is rejected. Deletion of existing branches Creation of new branches is controlled by the
is rejected. This is the safest mode as commits cannot be discarded. 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.
* +2 Create Branch * Force option
+ +
Implies 'Update Branch', but also allows the creation of a new branch Allows an existing branch to be deleted. Since a force push is
if the name does not not already designate an existing branch name. effectively a delete immediately followed by a create, but performed
Like update branch, existing commits cannot be discarded. 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.
* +3 Force Push Branch; Delete Branch The push category is primarily useful for projects that only want to
+
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 take advantage of Gerrit's access control features and do not need
its code review functionality. Projects that need to require code its code review functionality. Projects that need to require code
reviews should not grant this category. reviews should not grant this category.
[[category_READ_2]]
Upload Access
~~~~~~~~~~~~~
The `Read Access +2` permits the user to upload a non-merge commit [[category_push_review]]
to the project's `refs/for/BRANCH` namespace, creating a new change Upload To Code Review
for code review. ^^^^^^^^^^^^^^^^^^^^^
Rather than place this permission in its own category, its chained The `Push` access right granted on the namespace
into the Read Access category as a higher level of access. A user `refs/for/refs/heads/BRANCH` permits the user to upload a non-merge
must be able to clone or fetch the project in order to create a new commit to the project's `refs/for/BRANCH` namespace, creating a new
commit on their local system, so in practice they must also have change for code review.
Read Access +1 to even develop a change. Therefore upload access
implies read access by simply being a higher level of it. 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 For an open source, public Gerrit installation, it is common to
grant `Read Access +1..+2` to `Registered Users` in the `\-- All grant `Read` and `Push` for `refs/for/refs/heads/*`
Projects \--` ACL. For more private installations, its common to to `Registered Users` in the `All-Projects` ACL. For more
simply grant `Read Access +1..+2` to all users of a project. 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_READ_3]] [[category_READ_3]]
Upload Merge Access Upload Merge Access

4
Documentation/error-branch-not-found.txt
View File

@@ -25,8 +25,8 @@ If it was your intention to create a new branch you can either
'Admin' -> 'Projects' and browse your project, in the 'Branches' 'Admin' -> 'Projects' and browse your project, in the 'Branches'
tab you can then create a new branch). tab you can then create a new branch).
Please note that you need the access right '+2 Create Branch' in the Please note that you need to be granted the
link:access-control.html#category_pHD['Push Branch'] category to create new branches. link:access-control.html#category_create['Create reference'] access to create new branches.
GERRIT GERRIT

16
Documentation/error-prohibited-by-gerrit.txt
View File

@@ -8,15 +8,17 @@ privileges.
In particular this error occurs: In particular this error occurs:
1. if you push a commit for code review to a branch for which you 1. if you push a commit for code review to a branch for which you
don't have upload permissions (access right '+2 Upload permission' don't have upload permissions (access right
in the link:access-control.html#category_READ['Read Access'] category) link:access-control.html#category_push_review['Push'] on
2. if you bypass code review without sufficient privileges in the `refs/for/refs/heads/*`)
link:access-control.html#category_pHD['Push Branch'] category 2. if you bypass code review without
link:access-control.html#category_push_direct['Push'] privileges
on `refs/heads/*`
3. if you push a signed or annotated tag without sufficient 3. if you push a signed or annotated tag without sufficient
privileges in the link:access-control.html#category_pTAG['Push Tag'] category privileges in the link:access-control.html#category_pTAG['Push Tag']
4. if you push a lightweight tag without the access right '+2 Create
Branch' for the reference name 'refs/tags/*' in the link:access-control.html#category_pHD['Push Branch']
category category
4. if you push a lightweight tag without the access right link:access-control.html#category_create['Create
Reference'] for the reference name 'refs/tags/*'
For new users it happens often that they accidentally try to bypass For new users it happens often that they accidentally try to bypass
code review. The push then fails with the error message 'prohibited code review. The push then fails with the error message 'prohibited

6
Documentation/user-upload.txt
View File

@@ -279,9 +279,9 @@ or rewritten by the pusher.
* `refs/tags/*`: annotated tag objects pointing to any other type * `refs/tags/*`: annotated tag objects pointing to any other type
of Git object can be created. of Git object can be created.
To push branches, the `Push Branch` project right must be granted To push branches, the link:access-control.html#category_push_direct['Push']
to one (or more) of the user's groups. The allowed levels within right must be granted to one (or more) of the user's groups. The
this category are: allowed levels within this category are:
* Update: Any existing branch can be fast-forwarded to a new commit. * Update: Any existing branch can be fast-forwarded to a new commit.
This is the safest mode as commits cannot be discarded. Creation This is the safest mode as commits cannot be discarded. Creation