Finish Plugins

The finish step plugins implement actions to be performed after the test execution has been completed. These can be useful for finishing tasks such as an additional guest cleanup or uploading specific logs to an external server.

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:

name:

On command-line:

--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:

order:

On command-line:

--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:

summary:

On command-line:

--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:

when: RULE

On command-line:

--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:

where: GUEST|ROLE

On command-line:

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

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:

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

Multiple playbooks config:

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 order attribute to select in which order finishing tasks should happen if there are multiple configs. Default order is 50.

Configuration

See also 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:

extra-args: ANSIBLE-PLAYBOOK-OPTIONS

extra-args: -vvv

On command-line:

--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:

playbook: PATH|URL|NAMESPACE.COLLECTION.PLAYBOOK

On command-line:

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

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 test key specification for more details.

Example config:

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.

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

Use the order attribute to select in which order finishing tasks should happen if there are multiple configs. Default order is 50.

Configuration

See also 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:

ref: REVISION

On command-line:

--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:

script: SCRIPT

On command-line:

--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:

url: REPOSITORY

On command-line:

--url REPOSITORY
export TMT_PLUGIN_FINISH_SHELL_URL=REPOSITORY