// vim:set filetype=asciidoc:
[[watch]]
=== *debian/watch* file

NOTE: This file is for use by the Debian non-native package.

The **uscan**(1) command downloads the latest upstream version using the *debian/watch* file.  E.g.:

.Basic *debian/watch* file:
----
version=4
https://ftp.gnu.org/gnu/hello/ @PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@
----

The *uscan* command may verify the authenticity of the upstream tarball with optional configuration (see "`<<signing-key>>`").

See **uscan**(1), "`<<newversion>>`", "`<<files-excluded>>`", and "`<<gbp-manage>>`" for more.

[[signing-key]]
=== *debian/upstream/signing-key.asc* file

Some packages are signed by a openPGP key and their authenticity can be verified using their public openPGP key.

For example, "`https://www.gnu.org/software/hello/[GNU hello]`" can be downloaded via HTTP from https://ftp.gnu.org/gnu/hello/ .  There are sets of files:

* **hello-**__version__**.tar.xz** (upstream source)
* **hello-**__version__**.tar.xz.sig** (detached signature)

Let's pick the latest version set.

.Download the upstream tarball and its signature.
----
[base_dir] $ wget https://ftp.gnu.org/gnu/hello/hello-2.9.tar.xz
 ...
[base_dir] $ wget https://ftp.gnu.org/gnu/hello/hello-2.9.tar.xz.sig
 ...
[base_dir] $ gpg --verify hello-2.9.tar.xz.sig
gpg: Signature made Thu 10 Oct 2013 08:49:23 AM JST using DSA key ID 80EE4A00
gpg: Can't check signature: public key not found
----

If you know the public openPGP key of the upstream maintainer from the mailing list, use it as the *debian/upstream/signing-key.asc* file.  Otherwise, use the hkp keyserver and check it via your https://en.wikipedia.org/wiki/Web_of_trust[web of trust].

.Download public openPGP key for the upstream
----
[base_dir] $ gpg --keyserver hkp://keys.gnupg.net --recv-key 80EE4A00
gpg: requesting key 80EE4A00 from hkp server keys.gnupg.net
gpg: key 80EE4A00: public key "Reuben Thomas <rrt@sc3d.org>" imported
gpg: no ultimately trusted keys found
gpg: Total number processed: 1
gpg:               imported: 1
[base_dir] $ gpg --verify hello-2.9.tar.xz.sig
gpg: Signature made Thu 10 Oct 2013 08:49:23 AM JST using DSA key ID 80EE4A00
gpg: Good signature from "Reuben Thomas <rrt@sc3d.org>"
  ...
Primary key fingerprint: 9297 8852 A62F A5E2 85B2  A174 6808 9F73 80EE 4A00
----

TIP:  If your network environment blocks access to the HKP port *11371*, use "`*hkp://keyserver.ubuntu.com:80*`" instead.

After confirming the key ID *80EE4A00* is a trustworthy one, download its public key into the *debian/upstream/signing-key.asc* file.

.Set public openPGP key to *debian/upstream/signing-key.asc*
----
[base_dir] $ gpg --armor --export 80EE4A00 >debian/upstream/signing-key.asc
----

With the above *debian/upstream/signing-key.asc* file and the following *debian/watch* file, the *uscan* command can verify the authenticity of the upstream tarball after its download. E.g.:

.Improved *debian/watch* file with openPGP support:
----
version=4
opts="pgpsigurlmangle=s/$/.sig/" \
https://ftp.gnu.org/gnu/hello/ @PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@
----

[[salsa-ci-yml]]
=== *debian/salsa-ci.yml* file

Install https://salsa.debian.org/salsa-ci-team/pipeline[Salsa CI] configuration file.  See "`<<salsa-ci>>`".
