Debusine concepts

Artifacts

Artifacts are at the heart of Debusine. Artifacts are both inputs (submitted by users) and outputs (generated by tasks). An artifact combines:

  • an arbitrary set of files

  • arbitrary key-value data (stored as a JSON-encoded dictionary)

  • classification data:

    • a type

    • optionally, a slug, that is a unique string identifier

The type is just a string identifier used to recognize artifacts sharing the same structure. You can create and use types as you see fit but we have defined a basic ontology suited for the case of a Debian-based distribution.

Artifacts can have relations with other artifacts:

  • built-using: indicates that the build of the artifact used the target artifact (ex: “binary-packages” artefacts are built using “source-package” artefacts)

  • includes: indicates that the artifact conceptually includes the target artifact (ex: a “repository” artifact includes “binary-packages” artefacts)

  • extends: indicates that the artifact is extending the target artifact in some way (ex: a “source-upload” artifact extends a “source-package” artifact with target distribution information)

Artifacts are not deleted:

  • as long as they are referenced by another artifact (through one of the above relationships)

  • as long as their expiration date is not over

  • as long as they are not manually deleted (if they don’t have any expiration date)

Artifacts can have additional properties:

  • immutable: when set to True, nothing can be changed in the artifact through the API

  • creation timestamp: timestamp indicating when the artifact has been created

  • last updated timestamp: timestamp indicating when the artifact has been last modified/updated

The following operations are possible on artifacts:

  • create a new artifact

  • set key-value data

  • attach/remove a file

  • add/remove a relationship

  • publish the new artifact (trigger events that can be handled by configuration rules)

  • start an atomic update process on an existing artifact

  • delete an artifact

Rules

Rules are linking events related to artifacts (“new artifact”, “artifact deleted”, “artifact updated”) with tasks to execute or workflows to initiate.

They are defined in a configuration file. This is the main way available to the user to control the behaviour of debusine.

Tasks

Tasks are time-consuming operations that are typically offloaded to dedicated workers. They consume artifacts as input and generate artifacts as output. The generated artifacts automatically have built-using relationships linking to the artifacts used as input.

Tasks can require specific features from the workers on which it will run. This will be used to ensure things like:

  • architecture selection (when managing builders on different architectures)

  • required memory amount

  • required free disk space amount

  • availability of specific build chroot

Tasks are required to use the public API to interact with artifacts. They are passed a dedicated token that has the proper permissions to retrieve the required artifacts and to upload the generated artifacts.

Workflows

Workflows are advanced logic entirely driven by code. The code will usually trigger tasks and analyze the result of those tasks to decide on the next steps to execute.

Workflows are triggered through configuration rules.