|
|
| Line 1: |
Line 1: |
| Defining a policy on the hub allows you fine control over certain activities in the system. At present, policy allows you to control:
| | This document has moved to the [https://docs.pagure.org/koji/ Koji Documentation]. The new location is: |
| * tag/untag/move operations
| |
| * allowing builds from srpm
| |
| * allowing builds from expired repos
| |
| * managing the package list for a tag
| |
| * managing which channel a task goes to
| |
| In the future, we expect to add more policy hooks for controlling more aspects of the system.
| |
|
| |
|
| Policy configuration is optional. If you don't define one, then by default:
| | https://docs.pagure.org/koji/defining_hub_policies/ |
| * tag/untag/move operations are governed by tag locks/permissions
| |
| * builds from srpm are only allowed for admins
| |
| * builds from expired repos are only allowed for admins
| |
| * only admins may modify package lists
| |
| * tasks go to the default channel
| |
|
| |
|
| == Configuration ==
| | You can submit changes to Koji's docs in [https://pagure.io/koji Pagure] |
| | |
| The hub policy is configured in the <code>hub.conf</code> file, which is an ini-style configuration file. Policies are defined in the section named <code>[policy]</code>. Each <code>name = value</code> pair defines the policy of that name. With multiple line policies, successive lines should be indented so that the parser treats them as part of the whole.
| |
| | |
| Consider the following simple (and strict) example:
| |
| | |
| <pre>
| |
| [policy]
| |
| tag =
| |
| has_perm admin :: allow
| |
| tag *-candidate :: allow
| |
| all :: deny
| |
| </pre>
| |
| | |
| This policy section defines a single policy (named 'tag'). The policy is a series of rules, one per line. The rule lines must be indented. Each rule is a test and an action, separated by a double colon. The valid actions for current policies are 'allow' and 'deny'. There are many tests available, though not all of them are applicable for all policies. Each test is specified by giving the name of the test followed by any arguments the test accepts.
| |
| | |
| Each rule in the policy is checked until a match is found. Upon finding a match, the action is applied. Our example above limits non-admins to tags ending in -candidate.
| |
| | |
| Getting a bit more complicated
| |
| The example above is very simple. The policy syntax also supports compound tests, negated tests, and nested tests. Consider the following example:
| |
| | |
| <pre>
| |
| [policy] | |
| tag =
| |
| buildtag *epel* :: {
| |
| tag *epel* !! deny
| |
| }
| |
| tag *-updates :: {
| |
| operation move :: {
| |
| fromtag *-updates-candidate :: allow
| |
| fromtag *-updates-testing :: allow
| |
| all :: deny
| |
| }
| |
| operation tag && hastag *-updates-candidate *-updates-testing :: deny
| |
| }
| |
| all :: allow
| |
| </pre>
| |
| | |
| This policy sets up some rules concerning tags ending in -updates and tags containing epel, but is otherwise permissive.
| |
| | |
| The first nested rule limits builds built from a tag matching *epel* to only such tags. Note the use of !! instead of :: negates the test.
| |
| | |
| For tags matching *-updates, a particular work-flow is enforced. Moving is only allowed if the move is coming from a tag matching *-updates-candidate or *-updates-testing. Conversely, a basic tag operation (not a move) is denied if the build also has such a tag (the policy requires a move instead).
| |
| | |
| == General format ==
| |
| The general form of a basic policy line is one of the following
| |
| | |
| <pre>
| |
| test [params] [&& test [params] ...] :: action-if-true
| |
| test [params] [&& test [params] ...] !! action-if-false
| |
| </pre>
| |
| | |
| And for nested rules:
| |
| | |
| <pre>
| |
| test [params] [&& ...] [::|!!] {
| |
| test [params] [&& ...] [::|!!] action
| |
| test [params] [&& ...] [::|!!] {
| |
| ...
| |
| }
| |
| }
| |
| </pre>
| |
| | |
| Note that each closing brace must be on a line by itself.
| |
| Using !! instead of :: negates the entire test.
| |
| Tests can only be joined with &&, the syntax does not support ||.
| |
| | |
| == Available policies ==
| |
| The system currently looks for the following policies
| |
| * tag : checked during tag/untag/move operations
| |
| * build_from_srpm : checked when a build from srpm (not an SCM reference) is requested.
| |
| * build_from_repo_id : checked when a build from a specified repo id is requested
| |
| * package_list : checked when the package list for a tag is modified
| |
| * channel : consulted when a task is created
| |
| | |
| These policies are set by assigning a rule set to the given name in the policy section.
| |
| | |
| Note that the use of tag policies does not bypass tag locks or permissions
| |
| | |
| Note that an admin can bypass the tag policy by using --force.
| |
| | |
| == Actions ==
| |
| | |
| Most of the policies are simply allow/deny policies. They have two possible actions: allow or deny.
| |
| | |
| The channel policy is used to determine the channel for a task. It supports the following actions:
| |
| * use <channel>
| |
| ** use the given channel
| |
| * req
| |
| ** use the requested channel
| |
| ** generally this means the default, though some calls allow the client to request a channel
| |
| * parent
| |
| ** use the parent's channel
| |
| ** only valid for child tasks
| |
| ** recommend using the is_child_task test to be sure
| |
| | |
| == Available tests ==
| |
| '''true'''
| |
| * always true. no arguments
| |
| '''all'''
| |
| * an alias of true
| |
| '''false'''
| |
| * always false. no arguments
| |
| '''none'''
| |
| *an alias of false
| |
| '''operation'''
| |
| * for tag operations, the operation is one of: tag, untag, move. This test checks its arguments against the name of the operation and returns true if there is a match. Accepts glob patterns.
| |
| * only applicable to the tag policy
| |
| '''package'''
| |
| * Matches its arguments against the package name. Accepts glob patterns.
| |
| '''tag'''
| |
| * matches its arguments against the tag name. Accepts glob patterns.
| |
| * for move operations, the tag name tested is the destination tag (see fromtag)
| |
| * for untag operations, the tag name is null and this test will always be false (see fromtag)
| |
| * for the build_from_* policies, tests the destination tag for the build (which will be null is --skip-tag is used)
| |
| '''fromtag'''
| |
| * matches against the tag name that a build is leaving. Accepts glob patterns
| |
| * for tag operations, the tag name is null and this test will always be false
| |
| * for move operations, the tag name test is the one that the build is moving from
| |
| * for untag operations, tests the tag the build is being removed from
| |
| * only applicable to the tag policy
| |
| '''hastag'''
| |
| * checks the current tags for the build in question against the arguments.
| |
| '''buildtag'''
| |
| * checks the build tag name against the arguments
| |
| * for the build_from_* policies the build tag is determined by the build target requested
| |
| * for the tag policies, determines the build tag from the build data, which will by null for imported builds
| |
| '''skip_tag'''
| |
| * checks to see if the --skip-tag option was used
| |
| * only applicable to the build_from_* policies
| |
| '''imported'''
| |
| * checks to see if the build in question was imported
| |
| * takes no arguments
| |
| * true if any of the component rpms in the build lacks buildroot data
| |
| * only applicable to the tag policy
| |
| '''is_build_owner'''
| |
| * Check if requesting user owns the build (not the same as package ownership)
| |
| * take no arguments
| |
| '''user_in_group'''
| |
| * matches the users groups against the arguments
| |
| * true if user is in /any/ matching group
| |
| '''has_perm'''
| |
| * matches the user's permissions against the arguments
| |
| * true is user has /any/ matching permission
| |
| '''source'''
| |
| * test the build source against the arguments
| |
| * for the build_from_* policies, this is the source specified for the build
| |
| * for the tag policy, this comes from the task corresponding to the build (and will be null for imported builds)
| |
| '''policy'''
| |
| * takes a single argument, which is the name of another policy to check
| |
| * checks the named policy. true if the resulting action is one of: yes, true, allow
| |
| * additional policies are defined in the [policy] section, just like the others
| |
| '''is_new_package'''
| |
| * true if the package being added is new to the system
| |
| * intended for use with the package_list policy
| |
| '''is_child_task'''
| |
| * true if the task is a child task
| |
| * for use with the channel policy
| |
| '''method'''
| |
| * matches the task method name agaist glob pattern(s)
| |
| * true if the method name matches any of the patterns
| |
| * for use with the channel policy
| |
| '''user'''
| |
| * checks the username against glob patterns
| |
| * true if any pattern matches
| |
| * the user matched is the user performing the action
| |
| '''match'''
| |
| * matches a field in the data against glob patterns
| |
| * true if any pattern matches
| |
