.. _explanation-task-configuration:

==================
Task configuration
==================

Introduction
============

The behaviour of workflows and tasks is conditioned on the
input data that they are fed by users and parent workflows.

Task configuration is a mechanism available to workspace
owners to influence the input data before the task is scheduled
to run on a worker: Debusine will look up the ``task_configuration``
field in the work request to identify a
:collection:`debusine:task-configuration` collection and will apply
the instructions contained in that collection.

.. note::

    In most cases, the ``task_configuration`` field is unset and
    its default value (``default@debusine:task-configuration``) will
    be used.

.. caution::

    Task configuration can greatly influence the behaviour of the
    workflows and tasks. As such, when you create a workflow template,
    you should likely not allow users to override the value of
    the ``task_configuration`` field to make it point to a collection
    that they control.

    Modifications to collections are restricted to workspace owners,
    so users with the "workspace contributor" role will not be able
    to modify task configuration.

Use cases
=========

Manage special cases and exceptions
-----------------------------------

When you maintain a complete distribution like Debian or one of its
derivatives, you have to deal with special cases and exceptions, for
example:

* disable build/autopkgtest/etc. of a package on a specific architecture
  because it kills the workers
* restrict the build/autopkgtest/etc. of a package to specific workers
  where the build is known to succeed
* schedule a package only on workers with specific hardware requirements
* etc.

Control fields that are not set by workflows
--------------------------------------------

Many tasks offer multiple parameters that you cannot influence
through the parameters of the top-level workflow that you control.
With task configuration, it is possible to overcome that limitation
and inject values directly at the level of specific tasks.

Override fields that are set by workflows
-----------------------------------------

Workflows typically make some opinionated choices on the parameters
that they pass to their child work requests. In some cases, you might
want to make different choices and override the values provided by
the workflows. Task configuration enables this.

More documentation
==================

* :ref:`manage-task-configuration` covers how to create and maintain
  task configuration with YAML files in a git repository. It provides
  meaningful examples covering all the fields available in
  :bare-data:`debusine:task-configuration` entries.
* :ref:`task-configuration` is the reference documentation going
  into details about how task configuration is implemented.