[doc][defining_hub_policies] update the doc

docs/source/access_controls.rst

@@ -15,6 +15,8 @@ username/password but it has its limitations which you should be aware of.
 
 Details can be found at :ref:`auth-config`
 
+.. _allowed-scms:
+
 Allowed SCMs
 ============
 
@@ -24,6 +26,13 @@ We recommend that every production environment choose a limited set of trusted s
 
 Details of the ``allowed_scms`` option are covered under :ref:`scm-config`
 
+We also provides ``build_from_scm`` hub policy for the same purpose, you can choose either/both
+of the two approaches by the switch options in ``/etc/kojid.conf`` per build:
+
+    * ``allowed_scms_use_config``, default: ``true``
+    * ``allowed_scms_use_policy``, default: ``false``
+
+For more details of the ``build_from_scm``, please read :doc:`defining_hub_policies`.
 
 Hub Policies
 ============
@@ -43,6 +52,7 @@ Examples of access control polices are:
 * vm: control which windows build tasks are allowed
 * dist_repo: control which distRepo tasks are allowed
 * build_from_srpm: control whether builds from srpm are allowed
+* build_from_scm: control whether builds from the SCM are allowed and the behavior of the SCM
 * build_from_repo_id: control whether builds from user-specified repos ids are allowed
 
 Note that not all policies are access control policies.

docs/source/defining_hub_policies.rst

@@ -7,6 +7,8 @@ in the system. At present, policy allows you to control:
 
 * tag/untag/move operations
 * allowing builds from srpm
+* allowing builds from SCM, and managing properties/behaviors related to the SCM
+  if it is allowed
 * allowing builds from expired repos
 * managing the package list for a tag
 * managing which channel a task goes to
@@ -19,6 +21,11 @@ Policy configuration is optional. If you don't define one, then by default:
 
 * tag/untag/move operations are governed by tag locks/permissions
 * builds from srpm are only allowed for admins
+* builds from any SCM are only allowed for admins. It's used when
+  ``allowed_scms_use_policy`` is ``true`` in ``/etc/kojid.conf`` of the builders
+  (``false`` by default). And the SCM's properies: ``use_common`` and
+  ``source_cmd`` are set to their default values: ``False`` and
+  ``['make', 'source']``
 * builds from expired repos are only allowed for admins
 * only admins and users with ``tag`` permission may modify package lists
 * tasks go to the default channel
@@ -126,6 +133,7 @@ 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_scm``: checked when a build task from SCM is executing on builder
 * ``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
@@ -193,6 +201,23 @@ different:
 ``adjust -<int>``
     * decrement default priority
 
+The **build_from_scm** policy is used to assert if the SCM is allowed or not,
+like the basic allow/deny one. It is also used to manage the SCM's properties as
+the same as the ``allowed_scms`` option of the koji builder. The actions could
+be defined as:
+
+``allow [use_common] [<source_cmd>]``
+    * allow the SCM
+    * use(clone) the /common repo when ``use_common`` follows ``allow``
+    * ``<source_cmd>`` is a *optional* shell command for preparing the source
+      between checkout and srpm build. If it is omitted, it will follow the
+      default value: ``make source``. The explicit value: ``none`` means **No**
+      ``source_cmd`` is defined.
+
+``deny [<reason>]``
+    * disallow the SCM
+    * ``<reason>`` is the error message which is shown as the task result
+
 Available tests
 ===============
 ``true``

docs/source/server_howto.rst

@@ -1216,6 +1216,11 @@ SCM checkout can contain multiple spec files (checkouted or created by
 ``source_cmd``). In such case spec file named same as a checkout directory will
 be selected.
 
+.. note::
+    We provide ``build_from_scm`` hub policy as an equivalent in version 1.26.0.
+
+    For more details, please refer to :ref:`allowed-scms` and
+    :doc:`Defining Hub Policies <defining_hub_policies>`.
 
 Add the host to the createrepo channel
 --------------------------------------

koji/daemon.py

@@ -454,8 +454,8 @@ class SCM(object):
 
         The format of the action returned from build_from_scm could be one of following forms::
 
-            allow [use_common] [source_cmd]
+            allow [use_common] [<source_cmd>]
-            deny [reason]
+            deny [<reason>]
 
         If use_common is not set, use_common property is False.
         If source_cmd is none, it will be parsed as None. If it not set, the default value: