Translations: English - Português (Brasil)
tag2upload allows DDs and DMs to upload simply by using the git-debpush script to push a signed git tag.
Uploading
Use the git-debpush(1) program.
This replaces the whole upload flow (except, if you're using gbp pq you must gbp pq export). NB git debpush immediately and unconditionally initiates the upload, so you should already have run all your tests and lints (eg, Salsa CI).
git-debpush in bookworm and trixie are new enough for many use cases, but for the best user experience, use git-debpush version 16.x (currently in Debian testing and trixie-backports).
Most commonly-used git repository formats used in Debian are supported. For example, gbp pq is supported. See the "Quilt Mode Options" section in git-debpush(1).
Not supported
Uploads to NEW (even if only binary-NEW): ftp.d.o currently demands maintainer-generated binaries. You can use dgit instead.
Uploads to security-master. This is difficult: 862105.
Uploads to backports where your workflow involves throwing away the changelog entries for previous backports. I.e. if you start fresh for each version from testing you backport. If you do something like git checkout debian/bookworm-backports && git merge debian/latest and then resolve the debian/changelog merge conflict so as to preserve all entries, then it works (1109584).
NMUs that don't use the package maintainer's git repository, and git workflow, aren't likely to work well. Instead, use dgit, which offers a completely uniform git-based NMU workflow.
DELAYED/DEFERRED uploads (1123680).
Important links
git-debpush(1) - tag creation utility - the new way to upload
https://tag2upload.debian.org - Service status front page, with stats, logs, etc.
debian-tag2upload (at) lists.debian.org - mailing list receiving build logs, notices, etc. (not for discussion!)
tag2upload(5) - specification for the tag format
Notes and advice
Don't rewind your public branch, or delete already-pushed signed tags. This is always poor practice, because the git objects you're deleting might already have been fetched by someone. It's worse with tag2upload, because the service is very quick, and will fetch your tag almost immediately. The service always publishes the signed tag on its public mailing list (the audit log), even if the upload fails. If the upload succeeds, those git objects become part of the package history on {browse,git}.dgit.debian.org, leaving a permanent discrepancy.
If you make a mistake, simply bump the version (adding a new changelog stanza). Integers are plentiful.
Discrepancies between git, and the implied source package are not allowed. It's a fundamental design principle of the system that the source package and git view of the package are identical. For example, debian/source/local-options must be removed, or (if appropriate) renamed to debian/source/options. "Orig" tarballs must correspond to git: they must be generated from git (eg with git archive or git deborig), or imported into your maintainer branch (eg with gbp import-orig).
.gitattributes will be ignored, and their effects mustn't be visible in any existing orig tarballs. If upstream uses them for anything important, you must reproduce their effect in debian/rules and/or a Debian-specific patch. See GITATTRIBUTES in dgit(7) and #1079434 for more information, including rationale.
If you see "git-debpush: found upstream tags: v0.4.0 upstream/0.4.0 git-debpush: use --upstream=TAG to say which one to use": This can occur if you are pushing from a repository that has tags both from upstream (i.e., v0.4.0) and tags generated by gbp (i.e., upstream/0.4.0). In this situation, normally, you will want to use the gbp tag.
We recommend against gbp import-orig; use gbp import-ref instead. Usually, upstream is using git. Then, upstream git is the actual source code; the tarball is an intermediate build product. Using the upstream tarball is risky: if the tarball contents are not identical to the upstream git, gbp import-orig will prefer the tarball contents. It will do this silently, burying the differences in a synthetic commit which is hardly ever reviewed and is often unreviewable. Indeed, a discrepancy between git and tarball was a key technique used by the attacker to hide the xz backdoor. gbp import-ref (or simply git merge directly from upstream) avoids these risks. We appreciate that this advice is controversial within Debian; you can reject it and still use tag2upload: tag2upload fully supports use with gbp import-orig.
Falling back to dgit push for NEW packages
If you are used to using tag2upload, but want to upload a NEW package (including binary-NEW), you can use dgit instead. This works almost identically to tag2upload - but the work is done locally.
- Preparation
- Set up an appropriate sbuild chroot (or pbuilder if you prefer)
- Commit your changes, including to the changelog.
Run dgit instead of git-debpush:
dgit --gbp|--quilt=... sbuild
- Make your PGP key available
dgit --gbp|--quilt=... --trust-changelog --split-view=always push-built
git push salsa debian/VERSION
Notes:
Unlike git-debpush, dgit needs to be told the "quilt mode" for 3.0 (quilt) packages, if it's not linear. For gbp users, that's usually --gbp. For git-debrebase users, that's --quilt=linear (which is the default, so can be omitted). For non-quilt source package formats no quilt mode is needed.
dgit push-built will do all the necessary signing, tagging, and uploading. So don't run git tag. signchanges. dput, etc.
- Like tag2upload, dgit checks that your git tree and the source package correspond, that you're not accidentally overwriting an NMU, and so on. So there is no need to review your upload in source package form: do your review in git, before the formal build and push.
Monitoring and outputs; troubleshooting
Your upload should result in an email to you, CC the debian-tag2upload list; if successful it will show up in dgit fetch and on https://browse.dgit.debian.org (even before it has been ACCEPTed by the ftp archive). Note that sponsees don't get mail from tag2upload, but only from dak; tag2upload wants to feed back to the signer, not the Changed-By.
The tag2upload service page can show you the service's current and recent activity.
debian-tag2upload@lists.debian.org receives all reports from the tag2upload service, for monitoring and audit. It is a fully-functional public, archived, mailing list. (It should not be used for discussion.) The top level web view is currently missing the archives links, but you can go directly to the page for any month, for example https://lists.debian.org/debian-tag2upload/2025/05/threads.html
Web service informational API
Each of the web pages under https://tag2upload.debian.org is also available in an un-rendered JSON form. Simply send an Accept: application/json header. This is a read-only view.
The JSON schema is undocumented and unstable. But, hopefully this will be helpful. If you are using this feature, please contact us so we can try to avoid breaking your code.
Reporting problems, feedback
If something seems wrong, please don't hesitate to file a bug.
You may file bugs against git-debpush, even for problems with the service rather than the tag utility.
- We don't mind duplicate bugs: we can always merge them if necessary.
- Reports about poor user experience are also welcome.
For example, if git-debpush failed to spot a mistake it could have caught, or gave a poor error message, we want to know.
- Please don't file tickets in Salsa. We prefer bugs in the Bug Tracking System.
- Don't write to the debian-tag2upload@lists mailing list - that's for robots only.
- If you would like to email us privately, use dgit-owner at debian.org
You may have some luck with IRC. We are Diziet and spwhitton on OFTC. E.g., tag us in #debian-devel.
Signatures and traceability
tag2upload operates on instructions in the form of git tags, signed by uploading Debian contributors. The original git tag debian/VERSION for any successful upload can be obtained with git clone https://git.dgit.debian.org/PACKAGE.git.
The tag2upload service signs the tarball form of its uploads (including the .dsc) with a dedicated PGP signing key, currently 374D8CE4DB96E9CBD4C0972A606D084E4683C079. The public key is in debian-tag2upload-keyring.deb.
More information including the formal design documents is available in the dgit git repository. Information helpful for us as service operators, including a system deployment and dataflow diagram is in the dgit-infra-notes-scripts repository.
Credits
tag2upload was designed and implemented by Ian Jackson and Sean Whitton.
Russ Allbery did a security review, and his steadfast support was invaluable.
Thanks also to the many other people who gave practical, political, and moral support, including: Aigars Mahinovs; Alexander Wirt; Andrea Pappacoda; Aníbal Monsalve Salazar; Anton Gladky; Clare Boothby; Daniel Gröber; Didier 'OdyX' Raboud; intrigeri; Jacob Nevins; Jonathan McDowell; Ke Zhang; Marco d'Itri; Matthew Vernon; Matthias Urlichs; Nilesh Patra; Philip Hands; Sam Hartman; Simon Josefsson; Timo Röhling; Xiyue Deng.
License |
|
License |
CC BY-SA 4 |