1dgit-downstream-dsc(7) dgit dgit-downstream-dsc(7)
2
6 dgit-downstream-dsc - setting up dgit push for a new distro
7
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 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 Not every option is covered here. dgit(1) has a mostly-complete list
25 of config options, although not always with useful descriptions.
26
28 You need to choose some names.
29 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 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 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 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 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 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 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 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
69 You will need to run two parallel services:
70 git server
72 This will hold the git branches accessed by dgit.
73 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 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 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 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 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 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 dgit uses the term archive for this.
105 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 Setting up reprepro is not covered in this tutorial. Instead, we
111 assume you already have reprepro working.
112 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
119 When you have all of the above set up, you are ready to explain to dgit
120 how to access your systems.
121 dgit is configured via git's configuration system, so this is done with
123 git configuration. See git-config(1).
124 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 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 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 dgit-distro.distro/push.git-host
140 The domain name of your git server's ssh interface.
141 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 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 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 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 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 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 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 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 dgit-distro.distro/push.git-check, /push.git-create
179 dgit push also needs to be able to check whether the repo exists.
180 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 dgit-distro.distro.upload-host
188 What host value to pass to dput, to upload.
189 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 A good nickname for your upload host is your distro name distro.
195 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 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 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 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 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 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
225 When dgit push is used for package for the first time, it must create a
226 git repository on the git server.
227 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 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
237 When a user who can push runs dgit, dgit uses ssh to access the git
238 server.
239 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 The ssh commands used by dgit are these:
245 : 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 : 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 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 (There are also other ssh commands which are historical or obscure.)
263
265 dgit(1)
266perl v5.34.0 Debian Project dgit-downstream-dsc(7)