Lookups

Tasks and Workflows often need to refer to Artifacts and Collections. Rather than having to use raw IDs everywhere, this is normally done using lookups, written in a special-purpose query language. Lookups allow traversing collections to find items stored in them. Each category of collection defines lookup names tailored to the structure and content of the collection.

Some lookups resolve to a single artifact or collection, or raise an error if it cannot be found: these are called “single lookups”. For example, a common field in task data is environment, specifying a tarball or image that the task should use as its base execution environment. A single lookup that finds a bookworm image might be debian/match:codename=bookworm. This finds the debian collection (which in context is interpreted to be of the category debian:environments) and asks it to run the match lookup for codename=bookworm; the collection then returns a suitable artifact.

Some lookups resolve to multiple artifacts or collections, based on filters applied to the items in a collection: these are called “multiple lookups”. For example, a workflow might take a binary_artifacts field listing the binary artifacts that it should process. A multiple lookup that finds all the binary packages produced by the glibc source package in Debian’s trixie suite, regardless of architecture, might be:

collection: trixie@debian:suite
child_type: artifact
category: debian:binary-package
data__srcpkg_name: glibc

This finds the trixie collection of category debian:suite and then applies the given filters to all the items of that collection.

In some cases, lookups may resolve to promises rather than to real artifacts. These allow workflows to refer to artifacts that may not yet exist, but that are expected to be provided by other tasks or workflows. In conjunction with the internal collection associated with all workflows, this can be used to plug multiple sub-workflows together into more complex “pipelines”. For example, under a single root workflow, an autopkgtest sub-workflow that wants to consume the output of an sbuild sub-workflow might use:

binary_artifacts:
  collection: internal@collections
  child_type: artifact
  category: debian:upload
  name__startswith: build-

See Lookup syntax for reference documentation on writing lookups.