1dgit-downstream-dsc(7)               dgit               dgit-downstream-dsc(7)
2
3
4

NAME

6       dgit-downstream-dsc - setting up dgit push for a new distro
7

INTRODUCTION

9       This document is aimed at downstreams of Debian.  It explains how you
10       can publish your packages' source code both as traditional Debian
11       source packages, and as git branches, using dgit push.  Your users will
12       be able to get the source with dgit clone, or with traditional tools
13       such as apt-get source.
14
15       Note that often it is unnecessary to publish traditional source
16       packages.  Debian-format source packages can be complex, idiosyncratic
17       and difficult to work with.  You should avoid them if you can.  If you
18       do not need to publish source packages, you can work as a Debian
19       downstream purely using git branches, (using dgit to get the source
20       from Debian in git form).  You can build binaries directly from git,
21       and push package source code as a git branch to an ordinary git server.
22       See dgit-user(7).
23
24       Not every option is covered here.  dgit(1) has a mostly-complete list
25       of config options, although not always with useful descriptions.
26

NAMES

28       You need to choose some names.
29
30       distro name
31           dgit understands each thing it interacts with as a distro.  So in
32           dgit terms, you are setting up a distro.
33
34           You need a name for yourself (ie for your distro).  The name will
35           appear in the git tags made by your tools, and in configuration
36           settings.  It must be globally unique across all people and
37           institutions who use dgit.
38
39           You could choose your organisation's domain name, or a part of it
40           if you think that is going to be very unique.
41
42           The distro name may contain ascii alphanumerics and . + -, although
43           - may be confusing and is probably best avoided.  Try to avoid
44           uppercase letters (and underscore): you will be typing this name a
45           lot.
46
47           For example, if you were the Free Software Foundation Europe
48           (fsfe.org) you might call your distro fsfe or fsfe.org.  In the
49           rest of this document we will write distro for your distro name.
50
51       suite names
52           In dgit and Debian archive terminology, a suite is a line of
53           development, and/or a Debian release.  For example, at the time of
54           writing, Debian has suites like sid aka unstable, buster aka
55           testing, and stretch aka stable.  There are also ancillary suites
56           like stretch-security.
57
58           If your releases align with Debian's releases, then your suites
59           should contain the Debian suite names.  Do not use just the Debian
60           names.  That will cause confusion.  Instead, prepend your
61           organisation's name and a hyphen.  For example, FSFE might end up
62           with suites like fsfe-stretch.
63
64           Suite names end up in git ref and branch names, and on dgit command
65           lines.  Suite names can contain alphanumerics and "-".  Other
66           characters may work but are not recommended.
67

SERVICES

69       You will need to run two parallel services:
70
71       git server
72           This will hold the git branches accessed by dgit.
73
74           Everyone who will use dgit push needs to be able to update
75           refs/dgit/suite (note, not refs/heads/dgit/suite) on that server,
76           and to make tags distro/version and archive/distro/version.
77           Normally this would be done over ssh.
78
79           The server may host other branches and tags too.  So this might be
80           your ordinary git server, or an instance of a git hosting system.
81
82           Everyone who obtains one of your source packages, or who will run
83           dgit clone and  dgit fetch, needs to have at least read access to
84           the git server.  Ideally everything would be published via the git
85           smart https protocol.
86
87           The git server name, and public git url structure, should be chosen
88           so they will not need to change in the future.  Best is to give the
89           git server a DNS name of its own.
90
91           Debian's dgit git server has special access control rules,
92           implemented in dgit-repos-server and dgit-repos-policy-debian in
93           the package dgit-infrastructure.  but in most installations this is
94           not needed.  If there is no or little distinction between (i)
95           developers who are entitled to upload (push) and (ii) repository
96           administrators, then it is sufficient to provide a git server with
97           a unix account for each user who will be pushing, perhaps using ssh
98           restricted commands.
99
100       Debian-format archive (repository)
101           This holds the source packages.  You will probably use the same
102           archive to host your binaries, and point your apt at it.
103
104           dgit uses the term archive for this.
105
106           There are a variety of tools for creating and managing a Debian-
107           format archive.  In this document we will assume you are using
108           reprepro.
109
110           Setting up reprepro is not covered in this tutorial.  Instead, we
111           assume you already have reprepro working.
112
113           You should also write appropriate dput configuration, since dgit
114           uses dput to upload packages to the archive.  This will involve
115           choosing a dput host name.  That's probably your distro name,
116           distro.
117

CONFIGURATION

119       When you have all of the above set up, you are ready to explain to dgit
120       how to access your systems.
121
122       dgit is configured via git's configuration system, so this is done with
123       git configuration.  See git-config(1).
124
125       Below, each heading is one or more git config keys.  bold is literal
126       text and italics is things that vary.  In the descriptions of the
127       effects of config settings, we refer to the config values "like this".
128
129       dgit-distro.distro.git-url, .git-url-suffix
130           Specify the publicly accessible git URLs for your dgit git server.
131           The urls generated are "git-url"/package"git-url-suffix"
132
133           The url should be stable, and publicly accessible, because its name
134           is published in .dsc files.  (Note that if you make modified
135           versions of packages from Debian, the copyleft licences used for
136           Free Software often require you to permit your users, employees,
137           and downstreams to further distribute your modified source code.)
138
139       dgit-distro.distro/push.git-host
140           The domain name of your git server's ssh interface.
141
142       dgit-distro.distro/push.git-user-force dgit-distro.distro/push.username
143           Some git hosting systems expect everyone to connect over ssh as the
144           same user, often git.  If this is the case, set "git-user-force" to
145           that user.
146
147           If you have a normal git over ssh arrangement, where people ssh as
148           themselves, leave "git-user-force" unset.  If a user wishes to
149           override the username (for example, if their local username is not
150           the same as on the server) they can set "username".
151
152       dgit-distro.distro/push.git-url
153           Set this to the empty string.  This will arrange that push accesses
154           to the ssh server will use "/push.git-host", etc.
155
156       dgit-distro.distro/push.git-proto git+ssh://
157       "dgit-distro."distro/push.git-path
158           The path to your repositories.  dgit push will try to push to
159           "git-proto"["git-user-force"|"username"@]"git-path"/package.git
160
161       dgit-distro.distro.git-check, .git-check-suffix
162           dgit clone needs to be able to tell whether there is yet a git
163           repository for a particular package.
164
165           If you always have a git repository for every package in your
166           archive, perhaps because you never use dput/dupload, and always
167           dgit push, set "git-check" to true.
168
169           Otherwise, set "git-check" to a url prefix - ideally, https.  dgit
170           clone will try to fetch "git-check"/package"git-check-suffix" and
171           expect to get either some successful fetch (it doesn't matter what)
172           or a file not found error (http 404 status code).  Other outcomes
173           are fatal errors.
174
175           If your git server runs cgit, then you can set "git-check" to the
176           same as "git-url", and "git-check-suffix" to /info/refs.
177
178       dgit-distro.distro/push.git-check, /push.git-create
179           dgit push also needs to be able to check whether the repo exists.
180
181           You can set both of these to ssh-cmd, which will use an ssh shell
182           command to test repository existence.  Or leave them unset, and
183           dgit push will use the readonly details.  If repositories are
184           created automatically on push, somehow, you can set "git-create" to
185           true.
186
187       dgit-distro.distro.upload-host
188           What host value to pass to dput, to upload.
189
190           This is a nickname, not the real host name.  You need to provide
191           everyone who will push with an appropriate dput configuration.  See
192           dput.cf(5).
193
194           A good nickname for your upload host is your distro name distro.
195
196       dgit-distro.distro.mirror
197           Set this to the url of your source package archive.  This is the
198           same string as appears in the 2nd field of each sources.list entry.
199
200       dgit-distro.distro.archive-query, .archive-query-url
201           If you have a smallish distro, set "archive-query" to aptget: (with
202           a colon).
203
204           If your distro is large (eg, if it contains a substantial fraction
205           of Debian) then this will not be very efficient: with this setting,
206           dgit often needs to download and update Sources files.
207
208           For large distros, it is better to implement the Debian archive
209           ftpmaster API.  See <https://api.ftp-master.debian.org/>, and set
210           "archive-query" to ftpmasterapi: (with a colon) and
211           "archive-query-url" to your API base URL.  dgit uses these queries:
212           suites, dsc_in_suite/isuite/package and file_in_archive/pat (so you
213           need not implement anything else).
214
215           Alternatively, if your system supports the rmadison protocol, you
216           can set "archive-query" to madison:[madison-distro].  dgit will
217           invoke rmadison -umadison-distro.
218
219       dgit-suite.suite.distro distro
220           Set this for every one of your suites.  You will have to update
221           this when new suites are created.  If you forget, your users can
222           explicitly specify -d distro to dgit.
223

TEMPLATE GIT REPOSITORY

225       When dgit push is used for package for the first time, it must create a
226       git repository on the git server.
227
228       If "git-create" is set to ssh-cmd, dgit will use the user's shell
229       access to the server to cp -a _template.git package.git.  So you should
230       create _template.git with suitable contents.
231
232       Note that the ssh rune invoked by dgit does not do any locking.  So if
233       two people dgit push the same package at the same time, there will be
234       lossage.  Either don't do that, or set up dgit-repos-server.
235

SSH COMMANDS

237       When a user who can push runs dgit, dgit uses ssh to access the git
238       server.
239
240       To make use of ssh restricted command easier, and for the benefit of
241       dgit-repos-server, dgit's ssh commands each start with a parseable
242       commentish rune.
243
244       The ssh commands used by dgit are these:
245
246       : dgit distro git-check package ;...
247           Test whether package has a git repo on the server already.  Should
248           print 0 or 1 and a newline, and exit status zero in either case.
249           The rest of the command, after ;, is a shell implementation of this
250           test.  Used when "git-check" is set to ssh-cmd.
251
252       : dgit distro git-create package ;...
253           Create the git repository for package on the server.  See "TEMPLATE
254           GIT REPOSITORY", above.  The rest of the command is an appropriate
255           invocation of cd and cp.  Used when "git-create" is set to ssh-cmd.
256
257       git-receive-pack..., git-upload-pack...
258           dgit invokes git to access the repository; git then runs these
259           commands.  Note that dgit push will first do a git fetch over ssh,
260           so you must provide upload-pack as well as receive-pack.
261
262       (There are also other ssh commands which are historical or obscure.)
263

SEE ALSO

265       dgit(1)
266
267
268
269perl v5.36.0                    Debian Project          dgit-downstream-dsc(7)
Impressum