diff --git a/Documentation/access-control.txt b/Documentation/access-control.txt index 41745c9f09..fc4d527040 100644 --- a/Documentation/access-control.txt +++ b/Documentation/access-control.txt @@ -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 administrators can define a set of default access rights for -<>. Child projects inherit these +<>. Child projects inherit these access rights where they are resolved to the users that own the child project. Having default access rights for -<> assigned on a parent project may +<> assigned on a parent project may avoid the need to initially configure access rights for 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 Review server. -[[category_OWN]] + +[[category_owner]] Owner ~~~~~ @@ -568,60 +569,66 @@ further refine access, but only for references that begin with out more about this role. -[[category_pHD]] -Push Branch -~~~~~~~~~~~ +[[category_push]] +Push +~~~~ -This category permits users to push directly into a branch over SSH, -bypassing any code review process that would otherwise be used. +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. -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. -Creation of new branches is rejected. Deletion of existing branches -is rejected. This is the safest mode as commits cannot be discarded. +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. -* +2 Create Branch +* Force option + -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. +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. -* +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 +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_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. +[[category_push_review]] +Upload To 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. +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 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. +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_READ_3]] Upload Merge Access diff --git a/Documentation/error-branch-not-found.txt b/Documentation/error-branch-not-found.txt index 43d35465cd..e2dcff14b5 100644 --- a/Documentation/error-branch-not-found.txt +++ b/Documentation/error-branch-not-found.txt @@ -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' tab you can then create a new branch). -Please note that you need the access right '+2 Create Branch' in the -link:access-control.html#category_pHD['Push Branch'] category to create new branches. +Please note that you need to be granted the +link:access-control.html#category_create['Create reference'] access to create new branches. GERRIT diff --git a/Documentation/error-prohibited-by-gerrit.txt b/Documentation/error-prohibited-by-gerrit.txt index 90c937ee18..864b5ebcd1 100644 --- a/Documentation/error-prohibited-by-gerrit.txt +++ b/Documentation/error-prohibited-by-gerrit.txt @@ -8,15 +8,17 @@ privileges. In particular this error occurs: 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' - in the link:access-control.html#category_READ['Read Access'] category) -2. if you bypass code review without sufficient privileges in the - link:access-control.html#category_pHD['Push Branch'] category + don't have upload permissions (access right + link:access-control.html#category_push_review['Push'] on + `refs/for/refs/heads/*`) +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 - privileges in the link:access-control.html#category_pTAG['Push Tag'] category -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'] + privileges in the link:access-control.html#category_pTAG['Push Tag'] 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 code review. The push then fails with the error message 'prohibited diff --git a/Documentation/user-upload.txt b/Documentation/user-upload.txt index 58d7ba86b7..3ab48c9b32 100644 --- a/Documentation/user-upload.txt +++ b/Documentation/user-upload.txt @@ -279,9 +279,9 @@ or rewritten by the pusher. * `refs/tags/*`: annotated tag objects pointing to any other type of Git object can be created. -To push branches, the `Push Branch` project right must be granted -to one (or more) of the user's groups. The allowed levels within -this category are: +To push branches, the link:access-control.html#category_push_direct['Push'] +right must be granted to one (or more) of the user's groups. The +allowed levels within this category are: * Update: Any existing branch can be fast-forwarded to a new commit. This is the safest mode as commits cannot be discarded. Creation