:tocdepth: 0








.. _/plugins/prepare:

Prepare Plugins
~~~~~~~~~~~~~~~



.. include:: prepare-header.inc.rst

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

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:

    .. code-block:: yaml

       name:

    On command-line:

    .. code-block:: shell

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

    .. code-block:: yaml

       order:

    On command-line:

    .. code-block:: shell

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

    .. code-block:: yaml

       summary:

    On command-line:

    .. code-block:: shell

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

    .. code-block:: yaml

       when: RULE


    On command-line:

    .. code-block:: shell

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

    .. code-block:: yaml

       where: GUEST|ROLE


    On command-line:

    .. code-block:: shell

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



.. _/plugins/prepare/ansible:

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:

.. code-block:: yaml

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

.. code-block:: shell

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

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

.. code-block:: yaml

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

.. code-block:: shell

    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:

.. code-block:: yaml

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

.. code-block:: shell

    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 :ref:`Common Keys</plugins/prepare/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:

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

    .. code-block:: yaml

       playbook: PATH|URL|NAMESPACE.COLLECTION.PLAYBOOK


    On command-line:

    .. code-block:: shell

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



----


.. _/plugins/prepare/artifact:

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 in one of the
:tmt:story:`test require </spec/tests/require>`,
:tmt:story:`test recommend </spec/tests/recommend>`, or
:ref:`prepare install </plugins/prepare/install>`. 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.

Currently, the following artifact providers are supported:

**Koji**

Builds from the `Fedora Koji <https://koji.fedoraproject.org>`__ 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:

.. code-block:: yaml

    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:

.. code-block:: yaml

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

**Copr**

Builds from the `Fedora Copr <https://copr.fedorainfracloud.org>`__
build system.

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

Example usage:

.. code-block:: yaml

    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:

.. code-block:: yaml

    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:

.. code-block:: yaml

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




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



See also :ref:`Common Keys</plugins/prepare/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:

    .. code-block:: yaml

       default-repository-priority: PRIORITY


    On command-line:

    .. code-block:: shell

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

    .. code-block:: yaml

       provide: ID


    On command-line:

    .. code-block:: shell

       --provide ID
       export TMT_PLUGIN_PREPARE_ARTIFACT_PROVIDE=ID



----


.. _/plugins/prepare/feature:

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

   The plugin requires 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.

.. code-block:: yaml

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

.. code-block:: shell

    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 :ref:`Common Keys</plugins/prepare/common-keys>` accepted by the plugin.

.. include:: prepare-feature.rst



.. _/plugins/prepare/install:

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:

.. code-block:: yaml

    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.

.. code-block:: yaml

    # 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

.. code-block:: yaml

    # 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

.. code-block:: yaml

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

.. code-block:: yaml

    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).

.. code-block:: yaml

    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 :ref:`Common Keys</plugins/prepare/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:

    .. code-block:: yaml

       copr: REPO


    On command-line:

    .. code-block:: shell

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

    .. code-block:: yaml

       directory: PATH


    On command-line:

    .. code-block:: shell

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

    .. code-block:: yaml

       exclude: PACKAGE


    On command-line:

    .. code-block:: shell

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

    .. code-block:: yaml

       missing: ACTION


    On command-line:

    .. code-block:: shell

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

    .. code-block:: yaml

       package: PACKAGE


    On command-line:

    .. code-block:: shell

       --package PACKAGE
       export TMT_PLUGIN_PREPARE_INSTALL_PACKAGE=PACKAGE



----


.. _/plugins/prepare/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.

Prepare guest using shell (Bash) scripts.

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

.. code-block:: yaml

    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.

.. code-block:: yaml

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




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



See also :ref:`Common Keys</plugins/prepare/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:

    .. code-block:: yaml

       ref: REVISION


    On command-line:

    .. code-block:: shell

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

    .. code-block:: yaml

       script: SCRIPT


    On command-line:

    .. code-block:: shell

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

    .. code-block:: yaml

       url: REPOSITORY


    On command-line:

    .. code-block:: shell

       --url REPOSITORY
       export TMT_PLUGIN_PREPARE_SHELL_URL=REPOSITORY
