Merge changes Ifccd40c8,I3fc7a181 into stable
* changes:
Access control documentation: Final cleanup
Access control documentation: Read and Submit
diff --git a/Documentation/access-control.txt b/Documentation/access-control.txt
index ffeb62f..fdf40a0 100644
--- a/Documentation/access-control.txt
+++ b/Documentation/access-control.txt
@@ -1,17 +1,6 @@
Gerrit Code Review - Access Controls
====================================
-.Disclaimer
-****
-This documentation is outdated.
-
-In Gerrit 2.2.x the way how the access rights are configured has
-changed, but this documentation was not updated yet.
-
-This documentation still describes the access rights configuration as
-it was in Gerrit 2.1.8 and before.
-****
-
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. Access rights cannot be granted to individual
@@ -56,7 +45,7 @@
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]]
@@ -96,7 +85,7 @@
~~~~~~~~~~~~~~~~
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
@@ -109,7 +98,7 @@
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.
+on any change in any project they have `Read` access to.
Account Groups
@@ -205,12 +194,12 @@
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
@@ -220,20 +209,21 @@
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
@@ -246,13 +236,13 @@
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
~~~~~~~~~~~~~~~~~~~~~
@@ -287,9 +277,8 @@
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.
+behavior is generally only useful on the `Read` category when
+granting 'DENY' within a specific project to deny a group access.
[[access_category]]
@@ -490,7 +479,6 @@
stale branches.
-
[[category_forge_author]]
Forge Author
~~~~~~~~~~~~
@@ -676,38 +664,40 @@
option enabled 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
+[[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 `Read Access +1` in order to see a project, its
+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 Access -1`, and does not otherwise grant
-`Read Access \+1`, then a `Read Access +1` in the all projects ACL
+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 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.
+`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 Access +1` to `Registered Users` may be more
+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_SUBM]]
+
+[[category_submit]]
Submit
~~~~~~
@@ -728,17 +718,15 @@
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
diff --git a/Documentation/error-not-a-gerrit-project.txt b/Documentation/error-not-a-gerrit-project.txt
index f6e90fa..368a102 100644
--- a/Documentation/error-not-a-gerrit-project.txt
+++ b/Documentation/error-not-a-gerrit-project.txt
@@ -16,10 +16,11 @@
. Verify that you are pushing to the correct Gerrit server.
. Go in the Gerrit WebUI to 'Admin' -> 'Projects' and check that the
project is listed. If the project is not listed the project either
- does not exist or you don't have read access ('+1 Read Access' in
- the link:access-control.html#category_READ['Read Access'] category) for it. This means if you certain that
- the project name is right you should contact the Gerrit
- Administrator or project owner to request access to the project.
+ does not exist or you don't have
+ link:access-control.html#category_read['Read'] access for it. This
+ means if you certain that the project name is right you should
+ contact the Gerrit Administrator or project owner to request access
+ to the project.
This error message might be misleading if the project actually exists
but the push is failing because the pushing user has no read access
diff --git a/Documentation/error-not-allowed-to-upload-merges.txt b/Documentation/error-not-allowed-to-upload-merges.txt
index 3b52bc2..9aa144a 100644
--- a/Documentation/error-not-allowed-to-upload-merges.txt
+++ b/Documentation/error-not-allowed-to-upload-merges.txt
@@ -6,13 +6,15 @@
project to which the push is done.
If you need to upload merge commits, you can contact one of the
-project owners and request for this project permissions to upload
-merge commits (access right '+3 Upload merges permission' in the
-link:access-control.html#category_READ['Read Access'] category).
+project owners and request permissions to upload merge commits
+(access right link:access-control.html#category_push['Push'] and
+link:access-control.html#category_push_merge['Push merge']) for this
+project.
If one of your changes could not be merged in Gerrit due to conflicts
and you created the merge commit to resolve the conflicts, you might
-want to revert the merge and instead of this do a link:http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html[rebase].
+want to revert the merge and instead of this do a
+link:http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html[rebase].
GERRIT
diff --git a/Documentation/error-upload-denied.txt b/Documentation/error-upload-denied.txt
index 947280f..5dec8ab 100644
--- a/Documentation/error-upload-denied.txt
+++ b/Documentation/error-upload-denied.txt
@@ -8,8 +8,8 @@
There are two possibilities how to continue in this situation:
. contact one of the project owners and request upload permissions
- for the project (access right '+2 Upload permission' in the
- link:access-control.html#category_READ['Read Access'] category)
+ for the project (access right
+ link:access-control.html#category_push['Push'])
. export your commit as a patch using the link:http://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html[git format-patch] command
and provide the patch file to one of the project owners
