Workflows and Parameters

Workflows

.. gha:workflow:: <name>

Registers the workflow <name> - its file’s stem, as Parameters - with an index entry, and makes it the current workflow of the document: every gha:input, gha:output and gha:secret following it belongs to it, and a role may name its parameters without the workflow’s name.

The directive writes no visible output. Placed above the page’s title, its target is the title, as a label is.

:file: <path>: Path to the workflow file, relative to the document. Without it, the file is <name>.yml in gha_workflow_directory.

.. gha:workflow:: Parameters

Parameters
##########

The ``Parameters`` job template ...

A document using the workflow is read again, when the workflow file changed.

Inputs, Outputs and Secrets

Each of the three directives documents one parameter of the current workflow, as a section titled by the parameter’s name - so it is listed in the page’s table of contents - holding a field list:

the fields read from the workflow file: Type, Required and Default Value for an input and a secret, where — — — — says there is no default, and a multi-line default is shown as a block;
the fields of the directive’s content, in the order written, as Possible Values, Description or Example;
without a hand-written Description, the description of the workflow file, placed behind Type, Required, Default Value and Possible Values.

Content after the field list follows it. A workflow file states no type and no default for an output, so those fields are hand-written there.

Input Parameters
****************

.. gha:input:: package_name

   :Possible Values: Any valid Python package name.
   :Example:         ``myPackage``

Outputs
*******

.. gha:output:: python_jobs

   :Type:        string (JSON)
   :Description: A JSON array of job descriptions.

.. gha:input:: <name>

.. gha:output:: <name>

.. gha:secret:: <name>: Documents the input, output or secret <name> of the current workflow. Its target is <Workflow>.<name>.

.. gha:autoinputs::

Documents every input of the current workflow the document has no gha:input for - also those whose gha:input follows later in the document. An entry is what a gha:input without content creates: Type, Required, Default Value and the description of the workflow file.

Input Parameters
****************

.. gha:input:: package_name

   :Possible Values: Any valid Python package name.

.. gha:autoinputs::

Roles

:gha:workflow:

:gha:input:

:gha:output:

:gha:secret:

Refer to a workflow by its name, and to a parameter as <Workflow>.<name> - after a gha:workflow, the name alone refers to that workflow’s parameter. A leading ~ shows only the name:

:gha:input:`package_name`                 in the page of workflow 'Parameters'
:gha:input:`Parameters.package_name`      from anywhere
:gha:input:`~Parameters.package_name`     shown as 'package_name'
:gha:workflow:`CompletePipeline`

A target that isn’t documented is a warning.