Merge "Add parameterized builds (docs)"

doc/source/config/pipeline.rst

@@ -299,6 +299,16 @@ success, the pipeline reports back to Gerrit with ``Verified`` vote of
       :attr:`pipeline.require`, this can ensure that pipeline
       requirements are exhaustive.
 
+   .. attr:: allow-parameters
+      :default: false
+
+      If this is set to `true` then projects will be permitted to
+      specify parameters via :attr:`project.<pipeline>.parameters`
+      that should be supplied when enqueing changes to this pipeline.
+      The only way to specify parameters currently is via the web
+      interface or API, so this setting is generally only useful for
+      pipelines that are triggered manually.
+
    .. attr:: supercedes
 
       The name of a pipeline, or a list of names, that this pipeline

doc/source/config/project.rst

@@ -283,6 +283,55 @@ pipeline.
          can be forced to a specific value by e.g. defining it in a config
          repo.
 
+      .. attr:: parameters
+         :type: list
+
+         If :attr:`pipeline.allow-parameters` for this pipeline is set
+         to `true`, then this may be set to a list of parameters that
+         should be supplied by the user when enqueing changes.
+
+         .. attr:: name
+            :required:
+
+            The name of the parameter.  This must be a valid Ansible
+            variable name.
+
+         .. attr:: type
+
+            One of the following input types:
+
+            .. value:: string
+
+            .. value:: selection
+
+            .. value:: multiple-selection
+
+            .. value:: bool
+
+         .. attr:: description
+
+            Descriptive text about the parameter.
+
+         .. attr:: values
+            :type: list
+
+            If the parameter is a `selection` or `multiple-selection`,
+            this is a list of the permissible values.
+
+         .. attr:: default
+
+            A suggested default value.  This may be used by the web
+            interface or other client applications to supply a default
+            value, but it is not automatically used by Zuul if no
+            value is supplied with the enqueue command.
+
+         .. attr:: required
+
+            Whether the parameter is required.  This is provided to
+            the web interface and other client applications but is not
+            enforced by the enqueue command.
+
+
 .. _project-template:
 
 Project Template

doc/source/job-content.rst

@@ -100,6 +100,7 @@ order of precedence is:
 #. :ref:`Job extra variables <user_jobs_job_extra_variables>`
 #. :ref:`Secrets <user_jobs_secrets>`
 #. :ref:`Job variables <user_jobs_job_variables>`
+#. :ref:`Parameters <user_jobs_parameters>`
 #. :ref:`Project variables <user_jobs_project_variables>`
 #. :ref:`File variables <user_jobs_file_variables>`
 #. :ref:`Parent job results <user_jobs_parent_results>`
@@ -169,6 +170,20 @@ They are added to the ``vars`` section of the inventory file under the
 ``all`` hosts group, so they are available to all hosts.  Simply refer
 to them by the name specified in the job's ``vars`` section.
 
+.. _user_jobs_parameters:
+
+Parameters
+~~~~~~~~~~
+
+Any parameters specified when the item was enqueued are available to
+jobs as Ansible host variables in the same way as :ref:`job variables
+<user_jobs_job_variables>`.
+
+This is only supported for items manually enqueued using the web
+interface or API, and only in pipelines that support parameters with
+the :attr:`pipeline.allow-parameters` and
+:attr:`project.<pipeline>.parameters` configuration attributes.
+
 .. _user_jobs_project_variables:
 
 Project Variables

releasenotes/notes/parameterized-builds-c721c46c6f5fd3c6.yaml

@@ -0,0 +1,9 @@
+---
+features:
+  - |
+    Support for pipelines that run parameterized builds has been
+    added.  This supports a workflow where users may manually enqueue
+    branches or tags using the web interface while supplying
+    parameters that are passed to the resulting builds as Ansible
+    variables.  See the :attr:`pipeline.allow-parameters` and
+    :attr:`project.<pipeline>.parameters` configuration attributes.