config-project-config: Explain the format of access subsections
The format of the access sections was not explained at all and no
example was given.
The key for an access rule is the name of the access category in
lowerCaseCamel name (e.g. the key for "Create Tag" is "createTag"), with
2 exceptions: for "Create Reference" the key is "create" and for "Delete
Reference" the key is "delete". To address these exceptions rename these
access categories in the access-control documentation, but still keep
the verbose name in paranthesises since this is the name that is used in
the web UI.
For reference access-util.ts lists all access category keys.
Release-Notes: skip
Bug: Google b/312899496
Change-Id: Idc7e35ee6ec08a75b8600cf8097644124c3fd4b8
Signed-off-by: Edwin Kempin <ekempin@google.com>
diff --git a/Documentation/access-control.txt b/Documentation/access-control.txt
index 19a19dd..b37ee73 100644
--- a/Documentation/access-control.txt
+++ b/Documentation/access-control.txt
@@ -264,6 +264,7 @@
`-2..+2`, as the user's membership of `Foo Leads` effectively grant
them access to the entire reference space, thanks to the wildcard.
+[[exclusive]]
Gerrit also supports exclusive reference-level access control.
It is possible to configure Gerrit to grant an exclusive ref level
@@ -443,13 +444,13 @@
[[category_create]]
-=== Create Reference
+=== Create (aka 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 previously existing
-references (and also discard any commits in the process).
+The create 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 previously 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
@@ -484,9 +485,9 @@
`${username}` are still reachable by the users.
[[category_delete]]
-=== Delete Reference
+=== Delete (aka Delete Reference)
-The delete reference category controls whether it is possible to delete
+The delete category controls whether it is possible to delete
references, branches or tags. It doesn't allow any other update of
references.
@@ -1618,6 +1619,7 @@
Access to refs can be blocked, allowed or denied.
+[[block-rule]]
==== BLOCK
For blocking access, all rules marked BLOCK are tested, and if one
@@ -1643,6 +1645,7 @@
permissions when they are processed in the ALLOW/DENY processing, as
described in the next subsection.
+[[allow-rule]]
==== ALLOW
For allowing access, all ALLOW/DENY rules that might apply to a ref
@@ -1656,6 +1659,7 @@
This ordering lets project owners apply permissions specific to their
project, overwriting the site defaults specified in All-Projects.
+[[deny-rule]]
==== DENY
DENY is processed together with ALLOW.
diff --git a/Documentation/config-project-config.txt b/Documentation/config-project-config.txt
index be9e774..45004b0 100644
--- a/Documentation/config-project-config.txt
+++ b/Documentation/config-project-config.txt
@@ -852,13 +852,58 @@
[[access-subsection]]
==== Access subsection
-+access+ subsections for references connect access rights to groups. Each group
-listed must exist in the link:#file-groups[+groups+ file].
+`access` subsections define access rules for a ref or a ref namespace. The ref
+or ref namespace is specified as the subsection name and can be a concrete ref
+(e.g. `refs/heads/master`), a ref pattern (last path segment is '\*', e.g.
+`refs/heads/*`) or a regular expression (must start with '^', e.g.
+`^refs/heads/rel-.*`).
-Please refer to the
-link:access-control.html#access_categories[Access Categories]
-documentation for a full list of available access rights.
+[NOTE]
+For ref patterns '\*' can only appear as the last path segment. If a '*' is
+required in any other place the ref namespace must be specified as a regular
+expression (must start with '^', '\*' must follow what's being matched, e.g.
+".*" to match any string).
+The `access` subsections contain access rules that apply to the ref or ref
+namespace of the `access` subsections. The format of the access rules is: +
+`<accessCategoryId> = (block|deny)? <range>? group <group-name>`
+
+* `<accessCategoryId>`: ID of the link:access-control.html#access_categories[
+ access category] for which the access rule should be defined. The ID of the
+ access category is the name of the access category in lowerCamelCase (e.g.
+ `createTag`), except for label permissions where it is `label-<label-Name>`
+ (e.g. `label-Code-Review`).
+* `(block|deny)?`: `block` defines a link:access-control.html#block-rule[BLOCK]
+ rule, `deny` defines a link:access-control.html#deny-rule[DENY] rule, if
+ neither `block` or `deny` is specified an link:access-control.html#allow-rule[
+ ALLOW] rule is defined.
+* `<range>?`: Only set for label permission. The voting range in the format
+ `<min-vote>..<max-vote>` (e.g. `-1..+1`).
+* `group <group-name>`: The (local) name of the group to which the access rule
+ should apply (e.g. `group Foo Bar`). The (local) group name must exist in the
+ link:#file-groups[groups] file, so that Gerrit can resolve it to the group
+ UUID.
+
+To make access rules link:access-control.html#exclusive[exclusive] they need to
+be included into the value of the `exclusiveGroupPermissions` key: +
+`exclusiveGroupPermissions = <space-separated-list-of-access-category-ids>`
+
+.Example access subsections
+----
+ [access "refs/heads/*"]
+ create = group Administrators
+ delete = group Administrators
+ deleteChanges = group Administrators
+ label-Code-Review = -2..+2 group Maintainers
+ label-Code-Review = -1..+1 group Registered Users
+ label-Verified = -1..+1 group Registered Users
+ push = block Registered Users
+ submit = group Maintainers
+ exclusiveGroupPermissions = deleteChanges submit
+ [access "^refs/tags/rel-.*"]
+ createTag = group Maintainers
+ createSignedTag = group Maintainers
+----
[[mimetype-section]]
=== MIME Types section
