: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 :ref:`/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` 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 :ref:`/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 :ref:`/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` 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