.. workflow:: blhc

Workflow ``blhc``
====================

This workflow schedules :task:`Blhc` tasks to analyze the logs from builds.
A single :task:`Blhc` is scheduled for each artifact.

* ``task_data``:

  * ``prefix`` (string, optional): prefix this string to the item names
    provided in the internal collection
  * ``reference_prefix`` (string, optional unless
    ``enable_regression_tracking`` is set): prefix for the item names
    provided in the internal collection in the corresponding workflow run
    for reference tests

  * ``source_artifact`` (:ref:`lookup-single`, optional unless
    ``enable_regression_tracking`` is set): the
    :artifact:`debian:source-package` or :artifact:`debian:upload`
    source artifact that the build logs are based on
  * ``binary_artifacts`` (:ref:`lookup-multiple`; exactly one of this or
    ``package_build_logs`` must be set): the
    :artifact:`debian:binary-package` or :artifact:`debian:upload` binary
    artifacts whose related :artifact:`debian:package-build-log` artifacts
    should be analyzed
  * ``package_build_logs`` (:ref:`lookup-multiple`; exactly one of this or
    ``binary_artifacts`` must be set): the
    :artifact:`debian:package-build-log` artifacts to analyze

  * ``qa_suite`` (:ref:`lookup-single`, optional unless
    ``enable_regression_tracking`` is True or ``update_qa_results`` is
    either ``yes`` or ``force``): the :collection:`debian:suite` collection
    that reference tests are being run against to detect regressions
  * ``reference_qa_results`` (:ref:`lookup-single`, optional unless
    ``enable_regression_tracking`` is True or ``update_qa_results`` is
    either ``yes`` or ``force``): the :collection:`debian:qa-results`
    collection that contains the reference results of QA tasks to use to
    detect regressions
  * ``enable_regression_tracking`` (boolean, defaults to False): configure
    the workflow to detect and display regressions in QA results
  * ``update_qa_results`` (string, defaults to ``no``): whether to update
    reference QA results.  Allowed values are ``no``, ``yes``, and
    ``force``.  When set to ``yes``, the workflow runs QA tasks and updates
    the collection passed in ``reference_qa_results`` with the results,
    unless that collection already contains a current matching result.
    ``force`` is like ``yes``, but does not check whether the collection
    already contains a current matching result.

    For compatibility, boolean False is equivalent to ``no``, and boolean
    True is equivalent to ``yes``.

  * ``extra_flags`` (optional): a list of command-line flags to be passed
    to each scheduled :task:`Blhc` task

  * ``vendor`` (string, required): the distribution vendor, used to build
    ``environment`` for :task:`Blhc`
  * ``codename`` (string, required): the distribution codename, used to
    build ``environment`` for :task:`Blhc`

  * ``arch_all_build_architecture`` (string, defaults to ``amd64``): concrete
    architecture on which to run tasks for binary packages with
    ``Architecture: all``.

The workflow computes dynamic metadata as:

.. dynamic_data::
  :method: debusine.server.workflows.blhc::BlhcWorkflow.compute_dynamic_data

The lookup in ``package_build_logs`` may result in :bare-data:`promises
<debusine:promise>`, and in that case the workflow adds corresponding
dependencies.  Promises must include ``source_package_name`` and
``source_package_version`` fields in their data.
