Wiki

• FrontPage
• RecentChanges
• FindPage
• HelpContents
• tag2upload

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.

Beta status

Currently, tag2upload is in open beta. We think it is suitable for use in the following situations:

• You have your co-maintainers' blessing to try tag2upload. (Or, the maintainers' blessing, in the case of an NMU.)
• You'll be monitoring the output to check that everything seems in order, and be prepared to do some rework.
• You should carefully read the primary documentation:
  • This wiki page
  • The git-debpush(1) manpage

• You should use the latest git-debpush 13.x from forky (testing) or unstable.

• You should already be using git for packaging. 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).

• Previously you had to set up a webhook in gitlab manually. This is no longer needed as there is a global webhook for all repos on salsa.

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).

You need git-debpush version 11.11 or later (available in Debian trixie and bookworm-backports). (The version in bookworm-updates should also work.) For the best user experience, use git-debpush version 13.x (currently in Debian testing).

Not supported

• Uploads to NEW (even if only binary-NEW), because for those ftp.d.o currently demands maintainer-generated binaries.

• With a new upstream version, tag2upload will generate a fresh orig tarball with git archive (via git-deborig). This is OK, but it may surprise some users of pristine-tar. 1106071.

• 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.

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

• Adoption statistics

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. (Also there is currently a bug in this area, 1111548.)

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 is a fully-functional mailing list which accepts subscriptions and distributes and archives mail, but the web view for the list and its archives is currently broken. While listmaster figures that out, if you are a DD and need to access the archives, they're available in the usual place on master.debian.org.

(The webhook is configured globally, so, every tag will be notified to the tag2upload service. However, tags that don't look enough like tag2upload tags are ignored by the service. If your pushes seem to be being ignored, we administrators may be able to find more information in the tag2upload-manager logfiles.)

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.

When filing a bug, please provide, if available:

• A URL for the git tree (your Salsa repo)

• The precise commit that you were on when you ran git debpush. (If it's not already public, push it somewhere.)

• The jobid from the tag2upload service web page

• Any error messages you received

• The git-debpush invocation you used. (Shell session transcript is ideal.)

• Any REJECT mail you received from ftpmaster systems.

And, consider providing:

• The tag object, if a tag was produced but not pushed. You can get a copy from git cat-file tag debian/NNNN.

• Copies of automated emails you received (tag2upload service, "Debian queue daemon", ftpmaster systems). Use your judgement about which to forward. The messages from the tag2upload service are likely to be relevant.

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.

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.

CategoryDeveloper CategoryPackaging