Prepare Plugins

The prepare step is used to define how the guest environment should be prepared so that the tests can be successfully executed.

Common Keys

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

name

The name of the step phase.

Environment variable: TMT_PLUGIN_PREPARE_ANSIBLE_NAME

In plan metadata:

name:

On command-line:

--name ...
export TMT_PLUGIN_PREPARE_ANSIBLE_NAME=...

order

Order in which the phase should be handled.

Default: 50

Environment variable: TMT_PLUGIN_PREPARE_ANSIBLE_ORDER

In plan metadata:

order:

On command-line:

--order ...
export TMT_PLUGIN_PREPARE_ANSIBLE_ORDER=...

summary

Concise summary describing purpose of the phase.

Default: not set

Environment variable: TMT_PLUGIN_PREPARE_ANSIBLE_SUMMARY

In plan metadata:

summary:

On command-line:

--summary ...
export TMT_PLUGIN_PREPARE_ANSIBLE_SUMMARY=...

when

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

Default: not set

Environment variable: TMT_PLUGIN_PREPARE_ANSIBLE_WHEN

In plan metadata:

when: RULE

On command-line:

--when RULE
export TMT_PLUGIN_PREPARE_ANSIBLE_WHEN=RULE

where

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

Default: not set

Environment variable: TMT_PLUGIN_PREPARE_ANSIBLE_WHERE

In plan metadata:

where: GUEST|ROLE

On command-line:

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

ansible

Run Ansible playbooks against the guest, by running ansible-playbook for all given playbooks.

Note

The plugin requires a working Ansible to be available on the test runner.

Warning

When specifying playbooks with paths:

• If a metadata tree root exists, all paths must be relative to the metadata tree root.

• If the metadata tree root does not exist, all paths must be relative to the current working directory.

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.

Run a single playbook on the guest:

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

prepare --how ansible --playbook ansible/packages.yml

Run multiple playbooks in one phase, with extra arguments for ansible-playbook:

prepare:
    how: ansible
    playbook:
      - one.yml
      - two.yml
    extra-args: '-vvv'

prepare --how ansible --playbook one.yml --playbook two.yml --extra-args '-vvv'

Remote playbooks - provided as URLs starting with http:// or https://, local playbooks - optionally starting with a file:// schema, and playbooks bundled with collections can be referenced as well as local ones, and all kinds can be intermixed:

prepare:
    how: ansible
    playbook:
      - https://foo.bar/one.yml
      - two.yml
      - file://three.yml
      - ansible_galaxy_namespace.cool_collection.four

prepare --how ansible --playbook https://foo.bar/two.yml \
                      --playbook two.yml \
                      --playbook file://three.yml \
                      --playbook ansible_galaxy_namespace.cool_collection.four

Configuration

See also Common Keys accepted by the plugin.

extra-args

Additional CLI options for ansible-playbook.

Default: not set

Environment variable: TMT_PLUGIN_PREPARE_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_PREPARE_ANSIBLE_EXTRA_ARGS=ANSIBLE-PLAYBOOK-OPTIONS

--extra-args -vvv
export TMT_PLUGIN_PREPARE_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_PREPARE_ANSIBLE_PLAYBOOK

In plan metadata:

playbook: PATH|URL|NAMESPACE.COLLECTION.PLAYBOOK

On command-line:

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

---

artifact

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.

Prepare artifacts on the guest.

Note

This is a tech preview feature.

This plugin makes a given artifact available on the guest. This can consist of downloading the artifacts and creating a preferred repository on the guest.

The goal is to make sure these exact artifacts are being used when requested via test require or test recommend keys. Exact NVR should not be used in those requests, instead this plugin will take care of disambiguating the requested package based on the provided artifacts.

When verify is enabled (the default), the plugin injects a verification phase that checks packages installed from tmt-managed install phases (require, recommend, essential-requires, and their dist-git equivalents) actually came from the configured artifact repositories. User-defined prepare/install phases are not covered by this verification.

Currently, the following artifact providers are supported:

Koji

Builds from the Fedora Koji build system.

• koji.build:<build-id> - Koji build by build ID

• koji.task:<task-id> - Koji task (including scratch builds)

• koji.nvr:<nvr> - Koji build by NVR (name-version-release)

Example usage:

prepare:
    how: artifact
    provide:
      - koji.build:123456
      - koji.task:654321
      - koji.nvr:openssl-3.2.6-2.fc42

Brew (Red Hat internal)

Builds from the Red Hat Brew build system.

• brew.build:<build-id> - Brew build by build ID

• brew.task:<task-id> - Brew task (including scratch builds)

• brew.nvr:<nvr> - Brew build by NVR

Example usage:

prepare:
    how: artifact
    provide:
      - brew.build:123456
      - brew.task:654321
      - brew.nvr:openssl-3.2.6-2.el10

Copr

Builds from the Fedora Copr build system.

• copr.build:<build-id>:<chroot> - Copr build by ID and chroot

Example usage:

prepare:
    how: artifact
    provide:
      - copr.build:1784470:fedora-43-x86_64

File

RPMs from local files or remote URLs.

• file:<path> - Local RPM file(s) specified via path or a glob pattern

• file:<directory> - All RPMs from a local directory

• file:<url> - Remote RPM file URL (http/https)

Example usage:

prepare:
    how: artifact
    provide:
      - file:/tmp/my-package.rpm
      - file:/tmp/rpms/*.rpm
      - file:/tmp/rpms
      - file:https://example.com/my-package.rpm

Repository

Remote dnf repositories.

• repository-file:<url> - URL to a .repo file

Note

The repository-file provider only adds the dnf repository to the guest system, and does not download the RPMs from the repository.

Example usage:

prepare:
    how: artifact
    provide:
      - repository-file:https://example.com/my-repo.repo

Configuration

See also Common Keys accepted by the plugin.

default-repository-priority

Default priority for created artifact repositories. Lower values mean higher priority in package managers.

Default: 50

Environment variable: TMT_PLUGIN_PREPARE_ARTIFACT_DEFAULT_REPOSITORY_PRIORITY

In plan metadata:

default-repository-priority: PRIORITY

On command-line:

--default-repository-priority PRIORITY
export TMT_PLUGIN_PREPARE_ARTIFACT_DEFAULT_REPOSITORY_PRIORITY=PRIORITY

provide

Artifact ID to provide. Format <type>:<id>.

Default: not set

Environment variable: TMT_PLUGIN_PREPARE_ARTIFACT_PROVIDE

In plan metadata:

provide: ID

On command-line:

--provide ID
export TMT_PLUGIN_PREPARE_ARTIFACT_PROVIDE=ID

verify

Verify that packages from tmt-injected prepare/install phases (test require/recommend keys, their dist-git equivalents, and essential requires) were installed from the correct provider artifact repository. User-defined prepare/install phases are not covered.

Default: true

Environment variable: TMT_PLUGIN_PREPARE_ARTIFACT_VERIFY

In plan metadata:

verify: true|false

On command-line:

--verify
export TMT_PLUGIN_PREPARE_ARTIFACT_VERIFY=1|0

---

feature

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.

Easily enable and disable common features

The feature plugin provides a comfortable way to enable and disable some commonly used functionality such as enabling and disabling the epel repository or the fips mode.

Note

Some of the plugins require a working Ansible to be available on the test runner.

Warning

The plugin may be a subject of various limitations, imposed by the fact it uses Ansible to implement some of the features:

• Ansible 2.17+ no longer supports Python 3.6 and older. Guests where Python 3.7+ is not available cannot be prepared with the feature 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 feature plugin from an alternative repository or local build.

prepare:
    how: feature
    epel: disabled
    crb: enabled
    fips: enabled
    ...

prepare --how feature --epel disabled --crb enabled --fips enabled ...

Note

Features available via this plugin are implemented and shipped as plugins too. The list of available features and configuration keys will depend on which plugins you have installed.

See also Common Keys accepted by the plugin.

crb

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.

Enable or disable the CodeReady Builder (CRB) repository:

prepare:
    how: feature
    crb: enabled

prepare --how feature --crb enabled

Added in version 1.49.

crb

Whether the CRB repository should be enabled or disabled.

Default: not set

Environment variable: TMT_PLUGIN_PREPARE-FEATURE_CRB_CRB

In plan metadata:

crb: enabled|disabled

On command-line:

--crb 'enabled|disabled'
export TMT_PLUGIN_PREPARE-FEATURE_CRB_CRB='enabled|disabled'

---

epel

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.

Control Extra Packages for Enterprise Linux (EPEL) repository.

EPEL is an initiative within the Fedora Project to provide high quality additional packages for CentOS Stream and Red Hat Enterprise Linux (RHEL).

Enable or disable EPEL repository on the guest:

prepare:
    how: feature
    epel: enabled

prepare --how feature --epel enabled

epel

Whether EPEL repository should be installed & enabled or disabled.

Default: not set

Environment variable: TMT_PLUGIN_PREPARE-FEATURE_EPEL_EPEL

In plan metadata:

epel: enabled|disabled

On command-line:

--epel 'enabled|disabled'
export TMT_PLUGIN_PREPARE-FEATURE_EPEL_EPEL='enabled|disabled'

---

fips

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.

Enable FIPS mode on the guest.

Enable FIPS mode on RHEL 7, 8, 9 and 10 and CentOS Stream 8, 9 and 10 systems.

prepare:
    how: feature
    fips: enabled

prepare --how feature --fips enabled

Note

In order to prevent issues with installation of packages signed by non-FIPS-compliant algorithms we recommend enabling FIPS mode after package installation prepare steps. Use order: to enforce that.

Note

This feature plugin is not supported with container provisioner or with ostree-based distributions, e.g. Image Mode RHEL, Fedora CoreOS, etc.

Note

This plugin requires the following Ansible modules be installed on the runner:

• ansible.builtin.shell

• ansible.builtin.command

• ansible.builtin.dnf

• ansible.builtin.reboot

• ansible.builtin.raw

fips

Whether FIPS mode should be enabled

Default: not set

Environment variable: TMT_PLUGIN_PREPARE-FEATURE_FIPS_FIPS

In plan metadata:

fips: enabled

On command-line:

--fips enabled
export TMT_PLUGIN_PREPARE-FEATURE_FIPS_FIPS=enabled

---

profile

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.

Prepare guest setup with a guest profile.

Note

Guest profiles are being developed, once there is an agreed upon text we could steal^Wborrow^Wreuse, we shall add it to this docstring.

Guest profiles represent a particular setup of guest environment as defined by a CI system or service. They are implemented as Ansible roles, and packaged as Ansible collections. The CI systems use profiles to set up guests before testing, and users may use the same profiles to establish the same environment locally when developing tests or reprodcing issues.

Apply a profile to the guest:

prepare:
    how: feature
    profile: testing_farm.fedora_ci

prepare --how feature --profile testing_farm.fedora_ci

profile

Apply guest profile.

Default: not set

Environment variable: TMT_PLUGIN_PREPARE-FEATURE_PROFILE_PROFILE

In plan metadata:

profile: NAME

On command-line:

--profile NAME
export TMT_PLUGIN_PREPARE-FEATURE_PROFILE_PROFILE=NAME

install

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.

Install packages on the guest.

Example config:

prepare:
    how: install
    copr: psss/tmt
    package: tmt-all
    missing: fail

Use copr for enabling a desired Copr repository and missing to choose whether missing packages should be silently ignored (skip) or a preparation error should be reported (fail), which is the default.

One or more RPM packages can be specified under the package attribute. The packages will be installed on the guest. They can either be specified using their names, paths to local rpm files or urls to remote rpms.

# Install local rpms using file path
prepare:
    how: install
    package:
        - tmp/RPMS/noarch/tmt-0.15-1.fc31.noarch.rpm
        - tmp/RPMS/noarch/python3-tmt-0.15-1.fc31.noarch.rpm

# Install remote packages using url
prepare:
    how: install
    package:
      - https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
      - https://dl.fedoraproject.org/pub/epel/epel-next-release-latest-8.noarch.rpm

# Install the whole directory, exclude selected packages
prepare:
    how: install
    directory:
      - tmp/RPMS/noarch
    exclude:
      - tmt+all
      - tmt+provision-virtual

prepare:
    how: install
    # Repository with a group owner (@ prefixed) requires quotes, e.g.
    # copr: "@osci/rpminspect"
    copr: psss/tmt
    package: tmt-all
    missing: skip

Use directory to install all packages from given folder and exclude to skip selected packages (globbing characters are supported as well).

prepare:
    how: install
    directory: tmp/RPMS/noarch
    exclude: tmt+provision-virtual

Note

When testing ostree booted deployments tmt will use rpm-ostree as the package manager to perform the installation of requested packages. The current limitations of the rpm-ostree implementation are:

• Cannot install new version of already installed local rpm.

• No support for installing debuginfo packages at this time.

Configuration

See also Common Keys accepted by the plugin.

copr

Copr repository to be enabled.

Default: not set

Environment variable: TMT_PLUGIN_PREPARE_INSTALL_COPR

In plan metadata:

copr: REPO

On command-line:

--copr REPO
export TMT_PLUGIN_PREPARE_INSTALL_COPR=REPO

directory

Path to a local directory with rpm packages.

Default: not set

Environment variable: TMT_PLUGIN_PREPARE_INSTALL_DIRECTORY

In plan metadata:

directory: PATH

On command-line:

--directory PATH
export TMT_PLUGIN_PREPARE_INSTALL_DIRECTORY=PATH

exclude

Packages to be skipped during installation.

Default: not set

Environment variable: TMT_PLUGIN_PREPARE_INSTALL_EXCLUDE

In plan metadata:

exclude: PACKAGE

On command-line:

--exclude PACKAGE
export TMT_PLUGIN_PREPARE_INSTALL_EXCLUDE=PACKAGE

missing

Action on missing packages, fail (default) or skip.

Default: fail

Environment variable: TMT_PLUGIN_PREPARE_INSTALL_MISSING

In plan metadata:

missing: ACTION

On command-line:

--missing ACTION
export TMT_PLUGIN_PREPARE_INSTALL_MISSING=ACTION

package

Package name or path to rpm to be installed.

Default: not set

Environment variable: TMT_PLUGIN_PREPARE_INSTALL_PACKAGE

In plan metadata:

package: PACKAGE

On command-line:

--package PACKAGE
export TMT_PLUGIN_PREPARE_INSTALL_PACKAGE=PACKAGE

---

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.

Prepare guest using shell (Bash) scripts.

Default shell options are applied to the script, see the test key specification for more details.

prepare:
    how: shell
    script:
      - sudo dnf install -y 'dnf-command(copr)'
      - sudo dnf copr enable -y psss/tmt
      - sudo dnf install -y tmt

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_PREPARE_SHELL_URL_REPOSITORY will hold the value of the repository path.

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

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_PREPARE_SHELL_REF

In plan metadata:

ref: REVISION

On command-line:

--ref REVISION
export TMT_PLUGIN_PREPARE_SHELL_REF=REVISION

script

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

Default: not set

Environment variable: TMT_PLUGIN_PREPARE_SHELL_SCRIPT

In plan metadata:

script: SCRIPT

On command-line:

--script SCRIPT
export TMT_PLUGIN_PREPARE_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_PREPARE_SHELL_URL

In plan metadata:

url: REPOSITORY

On command-line:

--url REPOSITORY
export TMT_PLUGIN_PREPARE_SHELL_URL=REPOSITORY

---

verify-installation

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.

Verify that installed packages came from expected repositories.

Currently only supports DNF-based package managers (dnf, dnf5). Other package managers will cause the step to fail with an unsupported error.

Packages pre-installed in a container image (or otherwise not installed via a repository) report an unknown source. Such packages are attributed to <unknown> and can be matched by specifying '<unknown>' as the expected repository in the verification mapping.

Verification failures are recorded as FAIL results in the prepare phase output and cause the prepare step to fail, preventing test execution.

Each package may specify a single expected repository (string) or a list of acceptable repositories. A package passes if its actual source matches any of the listed repos.

Example usage:

prepare:
    how: verify-installation
    verify:
        make: tmt-artifact-shared
        gcc: fedora
        curl:
          - tmt-artifact-shared
          - updates

Configuration

See also Common Keys accepted by the plugin.

verify

Mapping of package names to expected source repository names. A package passes verification if it is installed and it was installed from one of the listed repositories. A single string value is accepted and treated as a one-element list.

Default: not set

Environment variable: TMT_PLUGIN_PREPARE_VERIFY-INSTALLATION_VERIFY

In plan metadata:

verify:

On command-line:

--verify ...
export TMT_PLUGIN_PREPARE_VERIFY-INSTALLATION_VERIFY=...