.. _checkout-task-configuration:

=========================================
Manage task configuration for a workspace
=========================================

.. note::

   This is only available to workspace owners.

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

Configuration that is common across *all* workflows in a workspace can
be configured in the workspace's :ref:`Workflow Templates
<explanation-workflow-template>`.
The Task Configuration collection can specify more complex
configuration.
It can provide defaults and enforce values in tasks, based on the
*subject* or *configuration context* of the task.

Data is stored in :bare-data:`debusine:task-configuration` entries in a
:collection:`debusine:task-configuration` collection.

Editing through text files
==========================

Debusine allows maintaining the collection in text files in a local
directory, preferably a ``git`` repository.

To initialize a task configuration git repository, follow these steps.
If you wish, you can follow the same process without using git, just
creating an empty directory to work in, and skipping the git steps.

#. Create a new git repository:

   .. code-block:: console

    $ git init task-config
    $ cd task-config

#. Pull the current collection contents into the repository:

   .. code-block:: console

    $ debusine --server NAME task-config pull --workspace WORKSPACE
    0 added, 0 updated, 0 deleted, 0 unchanged

#. This will create a ``METADATA`` file, and YAML files for any existing
   configuration.
   The workspace name is saved in this file, so we won't need to specify
   it again, when working with this repository.
#. Commit all of this to git:

   .. code-block:: console

    $ git add .
    $ git commit -m "Initialize workspace configuration repository"

#. Add configuration by making new YAML files, or editing existing files.
#. Commit the changes.
#. Push them back to the configuration collection:

   .. code-block:: console

    $ debusine --server NAME task-config push
    Pushing data to server...
    0 added, 0 updated, 0 removed, 1 unchanged

#. Push your git repo to somewhere that's shared with the other
   workspace admins.

The client will protect you from overwriting configuration if the
current server configuration is not in your git repository's history:

.. code-block:: console

    $ debusine --server NAME task-config push
    server collection was pushed from commit 148a8269de622667b7635d63c505b15a9ab8381d which is not known to ~/task-config

If you need to override this (maybe because you rewrote git history),
you can:

.. code-block:: console

    $ debusine --server NAME task-config push --force
    server collection was pushed from commit 148a8269de622667b7635d63c505b15a9ab8381d which is not known to ~/task-config
    Pushing data to server...
    0 added, 0 updated, 0 removed, 1 unchanged

Naming of files
---------------

``debusine:task-configuration`` entries pulled from the server are stored as
YAML files. The file names are ignored when matching remote entries with local
ones, so you can rename files and organize them into directories as you find it
convenient.

Multiple rules can be contained in a single file, by making a YAML list
of rules in one file.

When new entries are found on the server during a pull, they are stored inside
a ``new/`` directory from which they can be safely dispatched to a more
meaningful location in the checkout.

When pulling changes on existing files, debusine is able to locate the local
files according to their contents and update them in place.


Git and non-git
---------------

If the local checkout is in git:

* Push and pull refuse to work if there are uncommitted changes to ``.yaml``
  files.
* If an entry has been deleted on the server, it will also be deleted locally.
* Push will refuse to work if the server contents were pushed from git, and
  their commit hash is not an ancestor of the local git commit

If the local checkout is not in git:

* If an entry has been deleted on the server, it will not be deleted locally to
  prevent accidental data loss, although it will be reported in a warning.

You can use ``--force`` to bypass the checks above.


Dry run
-------

If using ``--dry-run``, push and pull operations will go through all the
motions, including download and upload of data and reporting of change
statistics, but changes are not stored in the database.


Example task configuration files
--------------------------------

YAML files in the checkout are the :bare-data:`debusine:task-configuration`
serialized to YAML. Here are a few examples of task configuration items.

A template entry with a name "reduce-parallelism" that sets sbuild's
``build_options`` to ``parallel=2`` in a forced manner:

.. code-block:: yaml

    template: reduce-parallelism
    override_values:
      build_options: parallel=2

A template entry that applies the "reduce-parallelism" template to :task:`Sbuild`
tasks for ``openjdk-17``:

.. code-block:: yaml

    task_type: Worker
    task_name: sbuild
    subject: openjdk-17
    use_templates: [reduce-parallelism]
    comment: reduce parallelism to avoid crashing workers

An entry that only builds ``u-boot`` on ARM by default:

.. code-block:: yaml

    task_type: Workflow
    task_name: debian_pipeline
    subject: u-boot
    default_values:
      architectures_allowlist: ['arm64', 'armhf']
    comment: only build on ARM by default


..
  Quick way to test these entries on ``debusine-admin shell``:

     from debusine.artifact.models import DebusineTaskConfiguration
     import yaml

     DebusineTaskConfiguration(**yaml.safe_load("""
     …entry…
     """))
