.. _taskotron-yaml-format: ========================== Taskotron Task YAML Format ========================== One of the core bits of Taskotron is the yaml file used to describe tasks to be run. As Taskotron is still a very young project, some components of the task yaml files are not yet used by the task runner but are useful to human readers of the task. Those sections will be noted and those notes updated as things change. The documentation here is a description of how things are implemented but are a little light on the practical creation of tasks. :ref:`writing-tasks-for-taskotron` and some existing tasks are also good references: * `rpmlint `_ * `examplebodhi `_ Task Description ================ Metadata -------- Some metadata is required to be in the task yaml file: * task name * description * maintainer .. code-block:: yaml --- name: rpmlint desc: download specified rpms and run rpmlint on them maintainer: tflink .. note:: Please use a FAS account name for the maintainer Input ----- Most tasks require some form of input. The required input must be declared in order to verify that the task can be run .. code-block:: yaml input: args: - arch - koji_build Valid args include: * arch (e.g.: ``x86_64``, ``[i386, x86_64]``) * koji_build (e.g.: ``xchat-0:2.8.8-19.fc19``, ``xchat-2.8.8-19.fc19``) * bodhi_id (e.g.: ``FEDORA-2013-10476``, ``xchat-2.8.8-19.fc19``) * koji_tag (e.g.: ``f20-updates-testing-pending``) Dependencies ------------ A task may also require the presence of other code to support execution. Those dependencies are specified as part of the environment description. .. code-block:: yaml environment: rpm: - rpmlint - libtaskotron .. note:: At this time, the list of rpm dependencies is not checked during execution but this will change in future versions. For now, this section is ignored and is mostly for human reference. .. note:: Future versions will also support specifying dependencies in other formats than RPM. Task Execution ============== Every task is defined in the ``task`` block of the task yaml file. The task consists of one or more steps which consist of a name, directive and optional export of data. .. code-block:: yaml task: - name: using directivename for something directivename: arg1: value1 arg2: ${some_variable} export: somestep_output Variable Storage and Syntax --------------------------- The task yaml file uses standard `string.Template`_ syntax for variables. You can use ``$variable`` or ``${variable}`` format, and you need to make the dollar sign doubled if you want to include it literally (``$$not_a_variable``). Variables can be created during task execution or provided by default by the task runner. .. _string.Template: https://docs.python.org/2.7/library/string.html?highlight=string#template-strings Provided Variables ------------------ The task runner provides the following variables without a need for them to be explicitly specified: * ``workdir`` * ``jobid`` .. note:: The ``jobid`` is used primarially for reporting to render proper log and job urls. It can be specified on the command line but isn't required for local execution. If a ``jobid`` is not explicitly provided at execution time, a sane default value will be provided by the runner. Created Variables ----------------- There are many situations in which the output from one step is used as input for another step which is executed later. In order for a step's output to be used later, it must first be exported. .. code-block:: yaml task: - name: first step directive_one: arg1: value1 export: firststep_output - name: second step directive_two: arg1: ${firststep_output} In this example, the output from ``first step`` is stored as ``firststep_output`` and later used by ``second step``. Once the ``first step`` is executed, its output is stored as a variable using the name following ``export:``. .. _taskotron-directives: Directives ========== The directives which are used in task steps are defined in libtaskotron. These directives are grouped into three types: preparation, execution and reporting. Below is a list of the current directives and what they can help you accomplish. This is not the complete documentation for each of these directives, but it should provide a good starting point for understanding what they do. .. note:: This directive documentation is incomplete and is meant to be temporary until we resolve `some issues `_ around generating documenation for the directives. For now, please see the source or ask questions about directives directly. bodhi_comment ------------- This is an interface to `bodhi `_ comments. Allows the posting of comments on a specific update as well as karma for the update. bodhi ----- This directive is used to download specific packages from `bodhi `_. createrepo ---------- Takes a path from yaml input and creates a repository on that path. dummy ----- Primarily a testing directive, it simply returns a status and optionally a message. Also works as a useful placeholder while writing new tasks. koji ---- Provides an interface to `koji `_ for downloading rpms with a specific NEVR or rpms with a specific tag. mash ---- Creates repositories from locally downloaded rpms. python ------ Allows the execution of a python script as part of task execution. Offers several methods of executing python code for a task. resultsdb --------- Provides an interface to `resultsdb `_ for storing results of executed tasks.