Taskotron Task Formula Format

One of the core bits of Taskotron is the formula yaml file used to describe tasks to be run. As Taskotron is still a very young project, some components of the task formulae 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. 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 formula:

• task name
• description
• maintainer

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

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. Anything that dnf install supports as an argument on the command line is supported.

environment:
    rpm:
        - python-solv
        - python-librepo

Note

Future versions will also support specifying dependencies in other formats than RPM.

Task Execution

Every task is defined in the actions block of the formula yaml file. The task consists of one or more actions which consist of a name, directive and optional export of data.

actions:
    - name: using directivename for something
      directivename:
          arg1: value1
          arg2: ${some_variable}
      export: somestep_output

Variable Storage and Syntax

The formula 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.

Provided Variables

The task runner provides the following variables without a need for them to be explicitly specified:

• artifactsdir contains a path to the artifacts directory. artifactsdir is used by tasks to store their various outputs like logs, archives, images or any other output. Artifacts, the content of artifactsdir, are then exposed and accessible via http, e.g. https://taskotron.fedoraproject.org/artifacts/20150423/0a93d8fa-ea09-11e4-9d4b-525400062113/. See also uuid.
• checkname, not suprisingly, contains a task name of the task currently being run by the runner. The reason why it’s not called taskname rather than checkname is that there were changes in Taskotron terminology in the past and the name persisted. Before 3rd party task support is introduced, the terminology will be unified.
• 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.
• uuid is an identification of a run which is unique across all parts of Taskotron. It can be specified on the command line. If a uuid is not explicitly provided at execution time, a sane default value will be provided by the runner.
• workdir is often used by Directives which store files that serve as inputs for the task about to be run by the runner. workdir also can be used for temporary files that the task might need during its execution.

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.

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

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.