Summaries

The directives below summarize the current workflow. Like the entries, they read the workflow file, so they can’t drift from it.

Parameter Tables

gha:parameter-table renders the summary tables of the current workflow’s parameters - one per kind, the parameters in file order, each name linked to its entry:

inputs - Parameter Name, Required, Type and Default;
secrets - Token Name, Required, Type and Default;
outputs - Result Name and the description of the workflow file.

A default longer than 120 characters, or of several lines, is shortened in the table and followed by …; the entry shows it in full.

Parameter Summary
*****************

.. rubric:: Inputs

.. gha:parameter-table::
   :kinds: inputs

.. rubric:: Secrets

.. gha:parameter-table::
   :kinds: secrets

.. gha:parameter-table::

:kinds: <kind> ...: The kinds of parameters to summarize, from inputs, secrets and outputs, separated by spaces or commas. The tables are rendered in the order written. Without the option, a table is rendered for every kind the workflow has parameters of, in the order inputs, secrets, outputs. A kind named here, of which the workflow has none, is a table saying so.

Interface

gha:interface renders the contract of the current workflow with its caller, as a field list:

Required Inputs, Secrets - a secret the caller has to pass is marked required - and Outputs, each linked to its entry;
Permissions - the permissions a caller has to grant the GITHUB_TOKEN. A called workflow can keep or reduce them, never raise them, so these are the permissions the workflow’s jobs and the jobs of the workflows they call declare - per scope the highest access, with the job and the line asking for it, linked to GitHub when gha_ref is configured.

What the workflow uses is listed by gha:dependencies.

.. topic:: Interface

   .. gha:interface::

.. gha:interface::: Summarizes the contract of the current workflow with its caller.

Dependencies

gha:dependencies renders what the current workflow uses, as a nested bullet list. From the workflow file, and from the files of the templates and actions it uses, as far as they are in the documented repository:

the templates the jobs call - each once, with the jobs calling it, when several do - each with its own dependencies. A template of the documented repository links to its page, one of another repository to GitHub;
the actions the steps run, each once, linked to GitHub. A composite action is listed with the actions its steps run, a Docker action with its image, read from its action.yml;
the images of the containers and service containers the jobs run in.

What a file can’t tell - packages a step installs, tools it calls - is the directive’s content: a bullet list merged into the derived one. An item whose text is the name of a derived item adds its nested list to that item, recursively; any other item is appended to its list. Content after the bullet list follows the list.

.. topic:: Dependencies

   .. gha:dependencies::

      * pyTooling/upload-artifact

        * :gh:`actions/upload-artifact`

      * pip

        * :term:`wheel`

.. gha:dependencies::

Lists the templates, actions and container images the current workflow uses, merged with the hand-written items of its content. A derived item is named by:

Derived item	Names
template	the reference as written, and without its ref, the file name, the file’s stem - as `UnitTesting.yml`
action	the reference as written, and without its ref - as `actions/checkout`
container	`container`, the image as written
service container	`service <name>`, the name, the image as written
image of a Docker action	`image`, the image as written

A file of the documented repository that doesn’t exist - a template or an action.yml - is a warning of type gha.workflow, and its item has no nested list.

YAML Excerpts

gha:yaml renders the current workflow’s file, or a part of it, as a YAML code block. The lines are numbered as in the file, and the part is shifted left by the indentation of its first line.

The caption names the file and the lines. When gha_repository and gha_ref are configured, it links to these lines on GitHub: https://github.com/<repository>/blob/<ref>/.github/workflows/<file>#L<first>-L<last>.

.. gha:yaml::
   :section: inputs

.. gha:yaml::
   :job: Package

.. gha:yaml::

:section: inputs | outputs | secrets | jobs: The inputs, outputs or secrets of on.workflow_call, or the jobs.

:job: <name>: One job. Excludes :section:. Without either option, the whole file is shown.

:caption: <text>: A caption replacing the file name and the lines.

:name: <label>: A label to reference the code block by.