:tocdepth: 0








.. _/plugins/finish:

Finish Plugins
~~~~~~~~~~~~~~



.. include:: finish-header.inc.rst

.. _/plugins/finish/common-keys:

Common Keys
-----------



The following keys are accepted by all plugins of the ``finish`` step.


name
    The name of the step phase.

    Environment variable: ``TMT_PLUGIN_FINISH_ANSIBLE_NAME``

    In plan metadata:

    .. code-block:: yaml

       name:

    On command-line:

    .. code-block:: shell

       --name ...
       export TMT_PLUGIN_FINISH_ANSIBLE_NAME=...



order
    Order in which the phase should be handled.

    Default: ``50``

    Environment variable: ``TMT_PLUGIN_FINISH_ANSIBLE_ORDER``

    In plan metadata:

    .. code-block:: yaml

       order:

    On command-line:

    .. code-block:: shell

       --order ...
       export TMT_PLUGIN_FINISH_ANSIBLE_ORDER=...



summary
    Concise summary describing purpose of the phase.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_FINISH_ANSIBLE_SUMMARY``

    In plan metadata:

    .. code-block:: yaml

       summary:

    On command-line:

    .. code-block:: shell

       --summary ...
       export TMT_PLUGIN_FINISH_ANSIBLE_SUMMARY=...



when
    If specified, phase is run only if any rule matches plan context.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_FINISH_ANSIBLE_WHEN``

    In plan metadata:

    .. code-block:: yaml

       when: RULE


    On command-line:

    .. code-block:: shell

       --when RULE
       export TMT_PLUGIN_FINISH_ANSIBLE_WHEN=RULE



where
    Run this phase on given guest or guests with the given role only.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_FINISH_ANSIBLE_WHERE``

    In plan metadata:

    .. code-block:: yaml

       where: GUEST|ROLE


    On command-line:

    .. code-block:: shell

       --where 'GUEST|ROLE'
       export TMT_PLUGIN_FINISH_ANSIBLE_WHERE='GUEST|ROLE'



.. _/plugins/finish/ansible:

ansible
-------



.. warning::

    Please, be aware that the documentation below is a work in progress. We are
    working on fixing it, adding missing bits and generally making it better.
    Also, it was originally used for command line help only, therefore the
    formatting is often suboptimal.

Perform finishing tasks using ansible.

One or more playbooks can be provided as a list under the ``playbook``
attribute.  Each of them will be applied using ``ansible-playbook`` in
the given order. The path must be relative to the metadata tree root.

Remote playbooks can be referenced as well as the local ones,
and both kinds can be used at the same time.

.. warning::

   The plugin may be a subject of various limitations, imposed by
   Ansible itself:

   * Ansible 2.17+ no longer supports Python 3.6 and older. Guests
     where Python 3.7+ is not available cannot be prepared with the
     ``ansible`` plugin. This has been observed when Fedora Rawhide
     runner is used with CentOS 7 or CentOS Stream 8 guests. Possible
     workarounds: downgrade Ansible tmt uses, or install Python 3.7+
     before using ``ansible`` plugin from an alternative repository
     or local build.

Single playbook config:

.. code-block:: yaml

    finish:
        how: ansible
        playbook: ansible/packages.yml

Multiple playbooks config:

.. code-block:: yaml

    finish:
        how: ansible
        playbook:
          - playbooks/common.yml
          - playbooks/os/rhel9.yml
          - https://foo.bar/rhel9-final-touches.yml

The playbook path should be relative to the metadata tree root. Use
the :tmt:story:`/spec/core/order` attribute to select in which order
finishing tasks should happen if there are multiple configs. Default
order is ``50``.




Configuration
^^^^^^^^^^^^^



See also :ref:`Common Keys</plugins/finish/common-keys>` accepted by the plugin.


extra-args
    Additional CLI options for ``ansible-playbook``.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_FINISH_ANSIBLE_EXTRA_ARGS``

    In plan metadata:

    .. code-block:: yaml

       extra-args: ANSIBLE-PLAYBOOK-OPTIONS

       extra-args: -vvv

    On command-line:

    .. code-block:: shell

       --extra-args ANSIBLE-PLAYBOOK-OPTIONS
       export TMT_PLUGIN_FINISH_ANSIBLE_EXTRA_ARGS=ANSIBLE-PLAYBOOK-OPTIONS

       --extra-args -vvv
       export TMT_PLUGIN_FINISH_ANSIBLE_EXTRA_ARGS=-vvv


playbook
    Path or URL of an Ansible playbook, or a playbook
    bundled within a collection, to run on a guest.
    Playbook ``PATH`` must be relative to the metadata tree
    root, if the metadata tree exists, or to the current
    working directory.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_FINISH_ANSIBLE_PLAYBOOK``

    In plan metadata:

    .. code-block:: yaml

       playbook: PATH|URL|NAMESPACE.COLLECTION.PLAYBOOK


    On command-line:

    .. code-block:: shell

       --playbook 'PATH|URL|NAMESPACE.COLLECTION.PLAYBOOK'
       export TMT_PLUGIN_FINISH_ANSIBLE_PLAYBOOK='PATH|URL|NAMESPACE.COLLECTION.PLAYBOOK'



----


.. _/plugins/finish/shell:

shell
-----



.. warning::

    Please, be aware that the documentation below is a work in progress. We are
    working on fixing it, adding missing bits and generally making it better.
    Also, it was originally used for command line help only, therefore the
    formatting is often suboptimal.

Perform finishing tasks using shell (bash) scripts.

Execute arbitrary shell commands to finish the testing.
Default shell options are applied to the script, see the
:tmt:story:`/spec/tests/test` key specification for more
details.

Example config:

.. code-block:: yaml

    finish:
        how: shell
        script:
          - upload-logs.sh || true
          - rm -rf /tmp/temporary-files

Scripts can also be fetched from a remote git repository.
Specify the ``url`` for the repository and optionally ``ref``
to checkout a specific branch, tag or commit.
``TMT_FINISH_SHELL_URL_REPOSITORY`` will hold the value of the
repository path.

.. code-block:: yaml

    finish:
        how: shell
        url: https://github.com/teemtee/tmt.git
        ref: main
        script: cd $TMT_FINISH_SHELL_URL_REPOSITORY && make docs

Use the :tmt:story:`/spec/core/order` attribute to select in which order
finishing tasks should happen if there are multiple configs. Default
order is ``50``.




Configuration
^^^^^^^^^^^^^



See also :ref:`Common Keys</plugins/finish/common-keys>` accepted by the plugin.


ref
    Branch, tag or commit to checkout in the git repository
    cloned when ``url`` is specified.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_FINISH_SHELL_REF``

    In plan metadata:

    .. code-block:: yaml

       ref: REVISION


    On command-line:

    .. code-block:: shell

       --ref REVISION
       export TMT_PLUGIN_FINISH_SHELL_REF=REVISION



script
    Shell script to be executed. Can be used multiple times.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_FINISH_SHELL_SCRIPT``

    In plan metadata:

    .. code-block:: yaml

       script: SCRIPT


    On command-line:

    .. code-block:: shell

       --script SCRIPT
       export TMT_PLUGIN_FINISH_SHELL_SCRIPT=SCRIPT



url
    URL of a repository to clone. It will be pushed to guests before
    running any scripts, the path on the guest will be stored in
    a step variable.

    Default: *not set*

    Environment variable: ``TMT_PLUGIN_FINISH_SHELL_URL``

    In plan metadata:

    .. code-block:: yaml

       url: REPOSITORY


    On command-line:

    .. code-block:: shell

       --url REPOSITORY
       export TMT_PLUGIN_FINISH_SHELL_URL=REPOSITORY
