1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
|
.. _tutorial-getting-started:
=============================
Getting started with Debusine
=============================
In this tutorial you will discover two of Debusine's building blocks:
:ref:`workflows <explanation-workflows>` and :ref:`artifacts
<explanation-artifacts>`. Workflows let you schedule the execution of
different kind of :ref:`tasks <explanation-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
<https://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
:ref:`tutorial-install-debusine`. 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 :ref:`supported package repositories
<debusine-package-repositories>`):
.. code-block:: console
$ sudo apt install debusine-client
Note that this documentation assumes that you have version 0.12.3 or
newer. If you use an older version, you might have to tweak some command
lines to use older syntaxes.
Now it's time to create yourself a token that the client will use to connect to
the server. Run ``debusine setup`` and follow the prompts (alternatively, manual
instructions are available in :ref:`create-api-token`).
More information about the Debusine command line interface is available
in :ref:`debusine-cli`.
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
:ref:`tutorial-set-up-workflow-templates` to prepare your Debusine instance for
running workflows.
Check workspace configuration
-----------------------------
Debusine organizes most objects into :ref:`workspaces
<explanation-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:
.. code-block:: console
$ 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:
.. code-block:: console
$ 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.
Start a workflow to build and test your package
-----------------------------------------------
Starting a :ref:`workflow <explanation-workflows>` asks the Debusine server to
do some work for you, possibly involving many smaller tasks. Debusine can run
many different :ref:`workflows <workflow-reference>` with many different
underlying :ref:`tasks <task-reference>`.
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 workflow start`` 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):
.. code-block:: console
$ debusine workflow start debian-qa-unshare <<END
source_artifact: 536
codename: trixie
END
Or, if you're using debusine.debian.net:
.. code-block:: console
$ debusine workflow start --workspace developers upload-to-unstable <<END
source_artifact: 536
END
This outputs some YAML structured information:
.. code-block:: yaml
result: success
message: Workflow created on http://debusine.internal/api with id 315.
workflow_id: 315
At this point, the server will run the workflow's implementation that will
create appropriate child work requests. Those will be executed 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 :workflow:`debian_pipeline` parameters and try
passing them to ``debusine workflow start`` 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 :artifact:`debian:upload`,
:artifact:`debian:binary-package`, and :artifact:`debian:package-build-log`
artifacts. You will also get a :artifact:`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:
.. code-block:: console
$ 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 :artifact:`debian:upload` artifact):
.. code-block:: console
$ 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
|
