.. task:: APTMirror

APTMirror task
--------------

This is a :ref:`server-side task <explanation-tasks>` that updates an
existing :collection:`debian:suite` collection to reflect the state of an
external APT suite.  It creates :artifact:`source <debian:source-package>`
and :artifact:`binary <debian:binary-package>` package artifacts as
required, as well as :artifact:`repository indexes
<debian:repository-index>`.

The ``task_data`` for this task may contain the following keys:

* ``collection`` (required): the name of the :collection:`debian:suite`
  collection to update
* ``url`` (required): the base URL of the external repository
* ``suite`` (required): the name of the suite in the external repository; if
  this ends with ``/``, then this is a `flat repository
  <https://wiki.debian.org/DebianRepository/Format#Flat_Repository_Format>`_
  and ``components`` must be omitted
* ``components`` (optional): if set, only mirror these components
* ``architectures`` (optional): if set, only mirror binary packages for this
  list of architectures
* ``signing_key`` (optional): ASCII-armored public key used to authenticate
  this suite
* ``filters`` (optional): a list of filters for which source and binary
  packages to mirror; each filter is a dictionary of conditions.  The
  filters are combined with "or" (so a package matched by any filter is
  selected), while the conditions in each filter are combined with "and" (so
  a filter only matches a package if all its conditions match).  If the
  ``filters`` parameter is omitted, all packages are mirrored.  The
  available conditions are as follows:

  * ``binary_name`` (regex): matches binary packages whose name matches this
    Python regular expression
  * ``priority`` (string): matches source or binary packages with this
    priority
  * ``section`` (string): matches source or binary packages with this
    section
  * ``source_name`` (regex): matches source packages whose name matches this
    Python regular expression, or any of their binary packages

  * ``ignore_unauthorized`` (boolean): no effect on which packages are
    matched, but if true, the task will ignore failures indicating
    insufficient authorization (HTTP 401 or 403) when downloading packages
    matched by this filter

* ``authentication`` (optional): the identifier of a
  :asset:`debian:apt-authentication` asset to use to authenticate to the
  external repository

The suite must have at least a ``Release`` file to make it possible to
handle multiple architectures in a reasonable way, and if ``signing_key`` is
specified then it must also have either an ``InRelease`` or a
``Release.gpg`` file.  Source and binary packages must have SHA256
checksums.

Additions and removals of collection items are timestamped as described in
:ref:`explanation-collections`, so tasks that need a static view of a
collection (e.g. so that all tasks in the same workflow instance see the
same base suite contents) can do this by filtering on collection items that
were created before or at a given point in time and were not yet removed at
that point in time.

.. todo::

   Document exactly how transactional updates of collections work in
   general: tasks need to see a coherent state, and simple updates to
   collections can be done in a database transaction, but some longer update
   tasks where using a single database transaction is impractical may need
   more careful handling.  See discussion in :mr:`517`.
