docs(web/guides): fix Linux apt install to dearmor GPG key before writing keyring - #2839
Conversation
…ting keyring apt requires the keyring file at /usr/share/keyrings/ to be in binary format. The previous snippet piped the ASCII-armored download straight through tee, causing an "unsupported filetype" warning and a NO_PUBKEY error on apt update. Swap tee for gpg --dearmor across all four Debian/Ubuntu snippets (stable and bleeding-edge in both the start-here and command-line-tools installation pages) and add a brief note in each GPG aside explaining why the dearmor step is needed. Fixes #2838 Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Wheels Bot — Docs proposedDraft PR: #2839 Pages updated:
Screenshots needed: none A human review is required before merge. The PR also carries a note flagging the separate empty-package-list ops issue that blocks installs regardless of the key fix. |
![wheels-bot[bot]](https://avatars.githubusercontent.com/in/3657588?s=60&v=4){kind=small}
There was a problem hiding this comment.
Wheels Bot — Reviewer A
TL;DR: This PR fixes a real, user-facing breakage: the Linux apt install snippets were piping the ASCII-armored GPG key straight into /usr/share/keyrings/ with tee, but apt's signed-by= mechanism requires a binary (dearmored) keyring, causing apt update to fail with "unsupported filetype." All four affected snippets (stable + bleeding-edge in both installing.mdx and installation.mdx) are corrected consistently, the GPG aside copy explains the reason, and CHANGELOG is updated. The diff is clean. Verdict: ready to merge (human approval required since the bot can't self-approve).
Correctness
The technical fix is correct. gpg --dearmor -o <file> is the canonical pattern for converting an ASCII-armored public key to the binary format required by /usr/share/keyrings/. Using -o instead of piping to tee is also a slight improvement: if curl -f propagates a non-zero exit but the shell lacks pipefail, gpg --dearmor will fail on empty/invalid input and produce a visible error, whereas the original tee would silently write garbage and succeed.
All four snippets are updated symmetrically:
web/sites/guides/src/content/docs/v4-0-0/command-line-tools/installation.mdxlines 58 and 75web/sites/guides/src/content/docs/v4-0-0/start-here/installing.mdxlines 180 and 196
The CHANGELOG ### Fixed block is inserted in the correct position (after ### Added, before ### Changed) in the [Unreleased] section.
Commits
docs(web/guides): fix Linux apt install to dearmor GPG key before writing keyring — type docs, unrestricted scope web/guides, sentence-case subject well under 100 characters. Compliant with commitlint.config.js.
Docs
Both prose asides are updated with a clear explanation of why the dearmor step is required. No code changes, so no test coverage is needed and no .ai/wheels/ layer docs are affected.
Wheels Bot — Reviewer B (round 1)A's review is technically sound, well-scoped for a pure docs change, and the verdict is consistent with the evidence. No significant issues found. Aligning on approve. SycophancyNone detected. A's positive verdict is backed by specific evidence: verified all four snippet changes, confirmed binary-format requirement is the root cause, checked CHANGELOG positioning and commit message compliance against False positivesNone detected. Spot-checked A's claims against the diff:
One minor imprecision: A says the original Missed issuesDCO: A did not explicitly verify the sign-off trailer. Checked the commit directly — No other missed issues. This is a docs-only change: no CFML code touched, no cross-engine compat concerns, no test coverage expected, no Verdict alignmentA's COMMENTED state with "ready to merge" is correct — the bot cannot self-approve, and the findings support an approve verdict. ConvergenceAligned. The fix is technically correct, the diff is clean, and A's verdict is appropriate. No changes needed. |
…obber on BE publish (#2846) * fix(distribution): dearmor apt key in docs + stop stable apt index clobber on BE publish Issue #2838 — the Debian/Ubuntu apt install path was broken two independent ways. 1. Docs (GPG key armor). Every snippet piped the ASCII-armored key served at apt.wheels.dev/wheels.gpg straight into /usr/share/keyrings/wheels.gpg with `tee`. Modern apt rejects an armored key in a signed-by= keyring ("unsupported filetype" -> NO_PUBKEY), so `apt update` failed verification and the install never worked. Switched all in-repo snippets to `sudo gpg --dearmor -o ...` — install guide, CLI installation reference, release-channels guide, the apt.wheels.dev landing page, and the tools/distribution-drafts templates — and noted why in each GPG aside. 2. Pipeline (empty stable index). regenerate-apt-metadata.sh rebuilt BOTH channels every run while the publish workflow synced only the dispatched channel's pool into the runner. A bleeding-edge publish (frequent) scanned an empty local pool/stable, emitted an empty Packages, and the unscoped `find dists` upload overwrote R2's good stable index — so `apt install wheels` returned "Unable to locate package wheels" even though the .deb was present in the pool. The regen now honors a CHANNELS env (the workflow passes the single dispatched channel) and the upload is scoped to dists/<channel>/, so the two channels can no longer clobber each other. These are the in-repo template copies. The live wheels-dev/apt-wheels repo carries the running copy and needs the same patch plus a one-off stable workflow_dispatch to rebuild the now-empty index (handled in a separate PR). Verified the clobber fix with a stubbed apt-ftparchive harness: the current script emits an empty dists/stable/Packages on a bleeding-edge run; with CHANNELS=bleeding-edge it emits none and leaves the stable index untouched. Supersedes the partial docs-only draft in #2839. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Peter Amiri <peter@alurium.com> * docs(distribution): address Reviewer A/B consensus findings (round 1) - web/content/blog/posts/wheels-4-0-2-released.md: swap `sudo tee` for `sudo gpg --dearmor -o` in the apt install snippet so the 4.0.2 release announcement no longer documents the NO_PUBKEY-failing form. - tools/distribution-drafts/apt-repo/templates/wheels.gpg.placeholder: same substitution in the internal bucket-repo minting instructions (B's additional missed occurrence). - CHANGELOG.md: append a parenthetical to the 4.0.2 "Added" entry noting the dearmor correction in #2846 (A's nit, lighter form). Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com> --------- Signed-off-by: Peter Amiri <peter@alurium.com> Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
|
Closing as superseded by #2846, which merged to Evidence this is fully redundant: rebasing this branch on current |
1 participant
The Debian/Ubuntu install snippets in both the start-here installing guide and the command-line-tools installation reference were piping the ASCII-armored GPG key directly into
/usr/share/keyrings/wheels.gpgviatee. apt'ssigned-by=mechanism requires the keyring file to be in binary (dearmored) format, so this produced an "unsupported filetype" warning and aNO_PUBKEYerror on everyapt update, making the install fail. The fix is to pipe throughsudo gpg --dearmor -o /usr/share/keyrings/wheels.gpginstead oftee.Four snippets are updated (stable + bleeding-edge in each of the two affected pages). The GPG aside in each page is also updated with a sentence explaining why the dearmor step is required, so the next reader who wonders about it doesn't have to open a bug.
Note for reviewers: The triage also flagged that the apt.wheels.dev package list is currently empty, so
apt install wheelsstill fails even with a working key. That is an ops/publishing-pipeline problem separate from this docs fix. This PR unblocks users who can work around the empty package list (e.g. by installing via the direct.debasset download) and cleans up the docs ahead of any pipeline fix.Fixes #2838
Screenshots needed
None — these are shell-snippet changes with no UI.