Getting started with Debusine
In this tutorial you will discover two of Debusine’s building blocks: workflows and artifacts. Workflows let you schedule the execution of different kind of tasks on remote workers, while artifacts represent a set of files managed by Debusine.
For the purpose of this tutorial, we will use Debusine’s command line interface to upload a source package, build it, and run various tests on it.
Prerequisites
You need to have access to a working Debusine instance:
If you are a Debian developer, you can use debusine.debian.net. You can login there with your salsa.debian.org account, and it will automatically create your Debusine account.
Otherwise, please follow the instructions from Install your first Debusine instance. Once completed, the Debusine instance will be available under the
debusine.internal
hostname and this is the name that we will continue to use here.
Install the client and configure it
You should first install the debusine-client
package (if needed
configure APT with one of the supported package repositories):
$ sudo apt install debusine-client
Now it’s time to create yourself a token that the client will use to connect to
the server. With debusine-client
version 0.10.0 or newer, you can run
debusine setup
and follow the prompts. With older versions, see
Create an API token.
More information about the Debusine command line interface is available in The debusine command.
Set up workflow templates
If you’re using a managed instance such as debusine.debian.net, you can skip this step. Otherwise, follow the instructions in Set up workflow templates to prepare your Debusine instance for running workflows.
Check workspace configuration
Debusine organizes most objects into workspaces, and you need to work within a workspace where you have at least the “contributor” role.
If you’re using your own instance, then the default workspace (System
) is
fine. Otherwise, you will need to add appropriate --workspace
options to
the commands below. For example, on debusine.debian.net, Debian developers may
use --workspace developers
(see https://wiki.debian.org/DebusineDebianNet
for more details).
Create an artifact by uploading a source package
The low-level debusine create-artifact
command can be used to create any
arbitrary artifact, but when it comes to Debian source packages (.dsc
)
or Debian uploads (.changes
), Debusine offers a more convenient
interface with debusine import-debian-artifact [FILE|URL]
. You can refer
to a local file or to a remote URL.
For instance, on your client, you can create and upload an artifact for the “hello” source package with:
$ debusine import-debian-artifact http://deb.debian.org/debian/pool/main/h/hello/hello_2.10-3.dsc
[...]
message: New artifact created in http://debusine.internal/api in workspace System with id 536.
artifact_id: 536
Or, if you’re using debusine.debian.net:
$ debusine import-debian-artifact --workspace developers \
http://deb.debian.org/debian/pool/main/h/hello/hello_2.10-3.dsc
Artifacts can be provided as input to many different Debusine workflows and tasks, using their artifact ID: take note of it.
Create a workflow to build and test your package
Creating a workflow asks the Debusine server to do some work for you, possibly involving many smaller tasks. Debusine can run many different workflows with many different underlying tasks.
It is up to each workspace owner to define which workflows their workspace
supports, using templates. You can find out what workflow templates are
currently available by looking at the workspace in the web interface (e.g.
http://debusine.internal/debusine/System/
or
https://debusine.debian.net/debian/developers/).
Once you know what workflow template you want to use, you can start a
workflow. The debusine create-workflow
command takes key-value
parameters for each workflow as YAML data on standard input. Try this on
your client, taking care to refer to the ID of the artifact that we created
in the previous step (536
for the source package in this example):
$ debusine create-workflow debian-qa-unshare <<END
source_artifact: 536
codename: trixie
END
Or, if you’re using debusine.debian.net:
$ debusine create-workflow --workspace developers upload-to-unstable <<END
source_artifact: 536
END
This outputs some YAML structured information:
result: success
message: Workflow created on http://debusine.internal/api with id 315.
workflow_id: 315
At this point, the task has not been executed yet, but it has been accepted and will be processed as soon as workers become available. You can follow the status of the workflow through the web interface (click on Workflows in the top menu to find it).
If the enable_upload
parameter is true (as in the upload-to-unstable
workflow on debusine.debian.net), then you will need to provide a signature
for the package if you’re happy with its QA results. Select the “Wait for
signature” work request in your workflow, and run the debusine
provide-signature
command it shows you. After that, Debusine will upload
the package to Debian for you.
You can explore the available debian_pipeline parameters and try passing them to debusine
create-workflow
to run your workflow in different ways.
Examine work requests and artifacts
You can explore the various work requests that are part of a workflow,
either in the web interface or using debusine show-work-request
. Work
requests typically have some input artifacts and some output artifacts. For
example, an sbuild
task will produce debian:upload, debian:binary-package,
and debian:package-build-log artifacts.
You will also get a debusine:work-request-debug-logs artifact containing various files
generated by Debusine to help troubleshoot issues with the task.
The generated artifacts can be browsed and downloaded from the web interface, or using the Debusine client:
$ debusine download-artifact 538
Downloading artifact and uncompressing into /home/debian
hello_2.10-3_amd64.deb
As well as the contained files, the artifact category also defines the
structure of the metadata that is associated with the artifact. You can
inspect those metadata and the file listing on the web interface or on the
command line with debusine show-artifact ARTIFACT_ID
(here 540
is
the artifact ID of a debian:upload
artifact):
$ debusine show-artifact 540
id: 540
workspace: System
category: debian:upload
created_at: '2024-01-24T17:05:04.975882+00:00'
data:
type: dpkg
changes_fields:
Date: Mon, 26 Dec 2022 16:30:00 +0100
[…]
download_tar_gz_url: http://debusine.internal/artifact/539/?archive=tar.gz
files_to_upload: []
expire_at: null
files:
hello_2.10-3_amd64.buildinfo:
size: 5511
checksums:
sha256: 422aef340c827d2ed2b38c353f660b70e754509bc0ddb0952975090d9f25caaa
type: file
url: http://debusine.internal/artifact/539/hello_2.10-3_amd64.buildinfo
hello_2.10-3_amd64.changes:
size: 1889
checksums:
sha256: d5d694b42b94587d38a5f883fe1fc5d44368ffe974ac3d506d55bcbef0ab0767
type: file
url: http://debusine.internal/artifact/539/hello_2.10-3_amd64.changes
hello_2.10-3_amd64.deb:
size: 53084
checksums:
sha256: 069754b87d7a546253554813252dacbd7a53e959845cc9f6e8f4c1c8fe3746c5
type: file
url: http://debusine.internal/artifact/539/hello_2.10-3_amd64.deb
hello-dbgsym_2.10-3_amd64.deb:
size: 35096
checksums:
sha256: 1550fcd93105a3cf8fddfc776fda0fbebb51dd7c2d2286eeabc43cb37896ad1e
type: file
url: http://debusine.internal/artifact/539/hello-dbgsym_2.10-3_amd64.deb