opendev/gerrit
Code Issues Proposed changes

Document the BLOCK access rule.

Browse Source 
The BLOCK access rules were introduced since
ae3b0598bf but the documentation was
missing.

Change-Id: If6a068f574e3200f891a7769701066302d1172c1
Signed-off-by: Sasa Zivkov <sasa.zivkov@sap.com>
This commit is contained in:
Sasa Zivkov
2013-02-12 14:27:09 +01:00
parent 5b8d4106d8
commit d589f463e3
1 changed files with 78 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
Documentation/access-control.txt
View File

@@ -1081,6 +1081,84 @@ Suggested access rights to grant:
* <<examples_project-owner,Project owner rights>>
Enforcing site wide access policies
-----------------------------------
By granting the <<category_owner,`Owner`>> access right on the `refs/*` to a
group, Gerrit administrators can delegate the responsibility of maintaining
access rights for that project to that group.
In a corporate deployment it is often necessary to enforce some access
policies. An example could be that no-one can update or delete a tag, not even
the project owners. The 'ALLOW' and 'DENY' rules are not enough for this
purpose as project owners can grant themselves any access right they wish and,
thus, effectively override any inherited access rights from the
"`All-Projects`" or some other common parent project.
What is needed is a mechanism to block a permission in a parent project so
that even project owners cannot allow a blocked permission in their child
project. Still, project owners should retain the possibility to manage all
non-blocked rules as they wish. This gives best of both worlds:
* Gerrit administrators can concentrate on enforcing site wide policies
and providing a meaningful set of default access permissions
* Project owners can manage access rights of their projects without a danger
of violating a site wide policy
'BLOCK' access rule
~~~~~~~~~~~~~~~~~~~
The 'BLOCK' rule blocks a permission globally. An inherited 'BLOCK' rule cannot
be overridden in the inheriting project. Any 'ALLOW' rule which conflicts with
an inherited 'BLOCK' rule will not be honored. Searching for 'BLOCK' rules, in
the chain of parent projects, ignores the Exclusive flag that is normally
applied to access sections.
A 'BLOCK' rule that blocks the 'push' permission blocks any type of push,
force or not. A blocking force push rule blocks only force pushes, but
allows non-forced pushes if an 'ALLOW' rule would have permitted it.
It is also possible to block label ranges. To block a group 'X' from voting
'-2' and '+2', but keep their existing voting permissions for the '-1..+1'
range intact we would define:
====
[access "refs/heads/*"]
label-Code-Review = block -2..+2 group X
====
The interpretation of the 'min..max' range in case of a blocking rule is: block
every vote from '-INFINITE..min' and 'max..INFINITE'. For the example above it
means that the range '-1..+1' is not affected by this block.
Examples
~~~~~~~~
The following examples show some possible use cases for the 'BLOCK' rules.
Make sure no one can update or delete a tag
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This requirement is quite common in a corporate deployment where
reproducibility of a build must be guaranteed. To achieve that we block 'push'
permission for the <<anonymous_users,'Anonymous Users'>> in "`All-Projects`":
====
[access "refs/tags/*"]
push = block group Anonymous Users
====
By blocking the <<anonymous_users,'Anonymous Users'>> we effectively block
everyone as everyone is a member of that group. Note that the permission to
create a tag is still necessary. Assuming that only <<category_owner,project
owners>> are allowed to create tags, we would extend the example above:
====
[access "refs/tags/*"]
push = block group Anonymous Users
create = group Project Owners
pushTag = group Project Owners
====
[[conversion_table]]
Conversion table from 2.1.x series to 2.2.x series