From d589f463e3b60de25b325c54ccc8df12612e06ab Mon Sep 17 00:00:00 2001 From: Sasa Zivkov Date: Tue, 12 Feb 2013 14:27:09 +0100 Subject: [PATCH] Document the BLOCK access rule. The BLOCK access rules were introduced since ae3b0598bf4c4d37163dd8fc49cb7bb538cc4281 but the documentation was missing. Change-Id: If6a068f574e3200f891a7769701066302d1172c1 Signed-off-by: Sasa Zivkov --- Documentation/access-control.txt | 78 ++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/Documentation/access-control.txt b/Documentation/access-control.txt index 1325b949b7..70e9cfded6 100644 --- a/Documentation/access-control.txt +++ b/Documentation/access-control.txt @@ -1081,6 +1081,84 @@ Suggested access rights to grant: * <> +Enforcing site wide access policies +----------------------------------- + +By granting the <> 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 <> in "`All-Projects`": + +==== + [access "refs/tags/*"] + push = block group Anonymous Users +==== + +By blocking the <> 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 <> 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