Repository navigation
chore: bootstrap the packages repository and its Pages site (#1) - #3
Conversation
Review — PR #3: bootstrap: initial repo with Pages site, CI, and docs (#1)Verdict: FAIL Reviewed head The supply chain and workflow security checks pass. The PR fails for two reasons:
There is also a latent CI bug: the shellcheck step breaks as soon as a second
Must fix
Should fix (non-blocking)
Acceptance criteria (#1)
Supply chain — verified
Workflow security — verified
Hygiene — verified
Branch rulesetRuleset
Uncertainty
|
Re-review: PR #3, chore: bootstrap the packages repository and its Pages site (#1)Verdict: FAIL Reviewed head Most of the 15 previous items are fixed: 10 fully and 5 partly. CI is now correct, and I checked it locally. The PR still fails, for two reasons:
Previous items: statusMust fix (from
|
| # | Item | Status | Evidence |
|---|---|---|---|
| 1 | No revocation procedure (AC 3) | partly fixed | docs/signing-key.md:34-54 now covers subkey A, subkey B and the primary key, and gives the location of the revocation certificate (:51-52). What users have to do is still wrong (:43, new Must fix 3), there is no CI update after a new subkey (:39, new Must fix 4), and the publish location is vague (:42). |
| 2 | Rotation steps contradict the key model | partly fixed | Fixed: the primary key is kept (:28-29), the garbled step 5 is gone, and the wording is now "generated and certified" (:7). Not fixed: the doc still never says to update APT_SIGNING_FINGERPRINT. The alternative "or add a new subkey" (:29) contradicts "the CI secrets do not change" (:31-32). New Must fix 4. |
| 3 | APT_SIGNING_FINGERPRINT listed as a secret |
fixed | docs/signing-key.md:22: it is now a Variable in apt-signing, holding "Subkey A's fingerprint with a ! suffix". |
| 4 | Export command missing | partly fixed | docs/signing-key.md:20 now gives gpg --armor --export-secret-subkeys <subkeyA-fpr>!, which is correct (tested). It calls the output "Base64-encoded", and it leaves out the re-protect step that gives the export a CI-only passphrase. New Must fix 5. |
| 5 | README.md:9: "signed with an offline primary key" |
fixed | README.md:9: "signed by subkey A (the primary key stays offline)". |
| 6 | AGENTS.md:27: wrong environment name |
fixed | AGENTS.md:27: github-pages. Its branch policy is main, which matches the API. |
| 7 | shellcheck got every file as one argument | fixed | ci.yml:61-62: git ls-files -z '*.sh' | xargs -0 -r …, and --severity=error is dropped. Tested with two files, one of them named a b.sh (see Local CI). |
| 8 | Tarballs extracted into the checkout | fixed | ci.yml:32 and ci.yml:44 now pass -C "$RUNNER_TEMP". After a local run, README.md and docs/ are untouched. The archives are still downloaded into the checkout (ci.yml:25,37, curl -fsSLO); see Should fix. |
Should fix (from da5fc08)
| # | Item | Status | Evidence |
|---|---|---|---|
| 1 | actionlint lists the workflow files by hand | fixed | ci.yml:57 passes no file arguments. Locally it found a planted .github/workflows/new.yaml. |
| 2 | Unused checksums.txt download |
fixed | The download is removed. The PR body still says "verified against the downloaded binary", but it is the tarball that gets verified. |
| 3 | pages.yml: no contents permission, no concurrency |
fixed | pages.yml:19 sets contents: read. pages.yml:20-22 sets concurrency: { group: pages, cancel-in-progress: false }. |
| 4 | README never says how to get the key | partly fixed | README.md:14-25 adds a download to /etc/apt/keyrings and gpg --show-keys. README.md:35-41 uses per-codename suites. But the file name is wrong (new Must fix 2), there is no fingerprint to compare against, the key is installed before it is verified, and gpg is not installed on stock images. |
| 5 | CLAUDE.md lacks the signing-secret rule |
fixed | CLAUDE.md:9. |
| 6 | No .deb guard |
fixed | .gitignore:1 holds *.deb, and ci.yml:46-53 adds a guard step. A planted, force-added pool/main/x_1.0_amd64.deb makes that step exit 1. |
| 7 | Link contrast in site/index.html |
fixed | site/index.html:10 uses #0b5394, which is 7.84:1 on white (AA needs 4.5:1). |
| 8 | PR title is not Conventional Commits | fixed | The title is now chore: bootstrap the packages repository and its Pages site (#1). |
Must fix
-
actionlint(repo root): a 5.8 MB compiled binary is committed. Commit6cb8c6cadded it.- It is the upstream actionlint 1.7.12 linux_arm64 binary: its sha256
ac032343…beb60matches the one inactionlint_1.7.12_linux_arm64.tar.gz. It is not malicious, but it is a stray build artefact from the implementer's machine. - The squash would add it to
mainfor good, and CI uses its own copy in$RUNNER_TEMPanyway. - Remove it with
git rm --cached actionlint. Also consider adding/actionlint,/shellcheck*and*.tar.*to.gitignore. - The PR body's file table leaves this file out.
- It is the upstream actionlint 1.7.12 linux_arm64 binary: its sha256
-
README.md:17: the keyring URL uses the wrong file name. The README downloads…/packages/mmt-archive-keyring.gpg.docs/signing-key.md:41and the maintainer procedure (§3, line 58) both producemontimage-archive-keyring.gpg, so the README URL will return 404. Use one name everywhere. The local path/etc/apt/keyrings/mmt.gpgcan stay as it is, but considermontimage-archive-keyring.gpgthere too. -
docs/signing-key.md:43: "Users refresh automatically on the nextapt update" is false. apt never fetches keys: theSigned-Byfile is whatever the user downloaded. I checked this indebian:bookwormandubuntu:22.04containers with a test key:- The user keeps the old keyring, and CI signs with the new subkey A2:
NO_PUBKEY C826D06F66A436C4, so the repo is not updated. - The same happens after a routine expiry extension (
:28). I faked the creation time so the subkey had already expired. gpgv with the old keyring givesNO_PUBKEYfor the extended subkey; the refreshed keyring givesGOODSIG.
So after any key change (revocation, a new subkey or a new expiry), users must download the keyring again. Say so in the doc and in the README. Better still, plan an
mmt-archive-keyringpackage so that apt updates the key itself. - The user keeps the old keyring, and CI signs with the new subkey A2:
-
docs/signing-key.md:29,31-32,39: a new subkey A means new CI secrets, but the doc says the opposite or says nothing.- The rotation alternative "add a new subkey" sits right next to "the CI secrets do not change".
- The subkey A revocation steps stop at republishing the keyring.
- Tested: when the user has the new keyring but CI still holds the revoked subkey A, apt fails with
REVKEYSIG 95694E33B66CACFC.
Add a step: export the new subkey with
--export-secret-subkeys "<new-subA-fpr>!", re-protect it, then updateAPT_SIGNING_KEY,APT_SIGNING_PASSPHRASEandAPT_SIGNING_FINGERPRINT(procedure steps 3–5). The previous item 2 asked for theAPT_SIGNING_FINGERPRINTupdate, and it is still missing. -
docs/signing-key.md:20-21: the export recipe as written puts the primary key's passphrase into CI.- On its own,
gpg --armor --export-secret-subkeys <fpr>!produces a file protected by the primary key's passphrase. - Line 21 says the passphrase is "CI-only, different from the primary's", but the doc gives no way to get there.
- The maintainer procedure (§4, lines 69-77) imports the file into a temporary
GNUPGHOME, runs--passwdthere, and only then re-exports. - Document that step, or link to it.
- Also,
--armoroutput is ASCII-armoured, not "Base64-encoded". The procedure stores the.ascfile as it is (gh secret set … < apt-signing-subkey.asc). If "Base64-encoded" stays, the future publish workflow may end up decoding it twice.
- On its own,
Should fix (non-blocking)
docs/signing-key.md:30: "Re-export the public key (step 3 below)" points nowhere. Step 3 below is "Send the new public files". The export command is at:41, and "step 3" comes from the maintainer procedure.docs/signing-key.md:28,38-41:$FPR,$SUBAandNare never defined. Say thatFPRis the primary key's fingerprint,SUBAis subkey A's, and thatNis the subkey's index in the--edit-keylisting.:28extends only$SUBA. The procedure extends"$SUBA" "$SUBB"together, and the published keyring contains both subkeys.
docs/signing-key.md:42: "Commit the new keyring to the repo so it is published on Pages" leaves out the path. Pages publishes onlysite/(pages.yml:29), so the doc should saysite/montimage-archive-keyring.gpg.docs/signing-key.md:47: subkey B is not handled only in mmt-dpi. It is revoked on the same offline primary key. The keyring published here contains subkey B (tested:--export-options export-minimal "$FPR"exports pub, A and B), so the keyring must be republished in this repo as well as in mmt-dpidebian/upstream/signing-key.asc.docs/signing-key.md:51: "Publish the revocation certificate" needs the how-to. The.revfile is guarded: line 21 is:-----BEGIN PGP PUBLIC KEY BLOCK-----. Remove the leading:, rungpg --import <FPR>.rev, then re-export the keyring intosite/.- Rotation by expiry extension (
:28-32) also needs the CI job to import the public key. I tested this. With the secret unchanged, CI signing with--local-user "$SUBA!"fails withUnusable secret keyonce the old expiry has passed, because the CI keyring still holds the old expiry. It works only after CI imports the refreshed public keyring. So "the CI secrets do not change" holds only if the future signing workflow importssite/montimage-archive-keyring.gpgbefore it signs. Write that down as a requirement for that workflow. - The README's install steps (
README.md:14-25) need four fixes:- Fingerprint: there is no fingerprint to compare against. The
da5fc08README said "will be published once the maintainer creates it", and that line is gone. Link todocs/signing-key.md#fingerprint(TBD). The PR body's AC 1 checkbox claims the README has this placeholder. - Order: verify the key before you install it. Download it to a temporary file, run
gpg --show-keys, then usesudo install -m 0644 <tmpfile> /etc/apt/keyrings/…. - gpg: stock
debian:bookwormandubuntu:22.04images have nogpg, onlygpgv. Mentionsudo apt-get install gnupg. - Directory:
/etc/apt/keyringsexists on both images, butsudo install -d -m 0755 /etc/apt/keyringsis a cheap guard.
- Fingerprint: there is no fingerprint to compare against. The
ci.yml:25,37: the archives are still downloaded into the checkout. It is harmless, because the.debguard usesgit ls-files. To keep the workspace clean,cd "$RUNNER_TEMP"beforecurl -fsSLO.AGENTS.md:21: "shellcheck and actionlint on all.github/workflows/*.ymlfiles" is not accurate. Shellcheck runs on tracked*.shfiles and, through actionlint, onrun:blocks. Actionlint also lints.yamlfiles.- PR body:
- The file table leaves out the
actionlintbinary. - "SHA256 verified against the downloaded binary" is wrong twice: it is the tarball that is verified.
- The AC 1 checkbox claims a README fingerprint placeholder that is no longer there.
- The squash commit uses the body, so it should be accurate.
- The file table leaves out the
For the maintainer (outside this PR)
These are in the maintainer's offline signing-key procedure:
- Line 102 sets
APT_SIGNING_FINGERPRINTto"<SUBA>"with no!. The key model you gave anddocs/signing-key.md:22both say it has the!. One of them should change. I recommend the!, because it stops gpg from picking another signing-capable subkey. - §6 has the same two gaps as Must fix 3 and the expiry should-fix:
- users must download the keyring again after an expiry extension or a new subkey;
- CI must import the refreshed public key before it signs.
Acceptance criteria (#1)
| # | Criterion | Status | Evidence |
|---|---|---|---|
| 1 | README: what it serves, the URL, retention, deb822 .sources + Signed-By, no apt-key, the fingerprint once it exists |
partial | All are present. The deb822 stanza works in a container with Suites: bookworm/jammy and Signed-By. The keyring URL has the wrong file name (Must fix 2). The fingerprint is deferred, which is acceptable, but nothing points to where it will be published. |
| 2 | AGENTS.md + CLAUDE.md: no .deb; secret only in apt-signing, never printed; full-SHA pins; no AI trailers |
pass | AGENTS.md:7-17,27-28 and CLAUDE.md:7-11. |
| 3 | signing-key.md: key model, CI secret names, rotation and revocation, no secret | partial | The key model matches the procedure: an offline ed25519 primary key, certify-only, 5 years (:5); subkeys A and B, signing-only, 2 years (:6-12); subkey B only in mmt-dpi (:12). The secret names are right, the variable is right (:22), and the export uses --export-secret-subkeys <fpr>! (:20). Revocation covers A, B and the primary key, and the fingerprint is a TBD placeholder (:58). The doc contains no secret. The rotation and revocation steps are wrong in places (Must fix 3–5). |
| 4 | A pinned Pages workflow deploys a placeholder reachable at montimage.github.io/packages | pass (pre-merge) | Reachability can only be checked after merge. |
| 5 | PR CI runs shellcheck + actionlint at pinned versions | pass | actionlint 1.7.12 and shellcheck 0.11.0, both checksum-verified. |
GnuPG commands tested
I ran these in a throwaway GNUPGHOME under the scratchpad, with a test key (test@example.invalid), no passphrase, and GnuPG 2.4.4. No real key was touched.
| Doc line | Command | Result |
|---|---|---|
| procedure §1 | --quick-generate-key … ed25519 cert 5y, --quick-add-key "$FPR" ed25519 sign 2y ×2 |
pub [C] expires +5y; two subs, caps s, expire +2y ✓ |
signing-key.md:20 |
gpg --armor --export-secret-subkeys "$SUBA!" |
exports sec# and one ssb ✓. Without ! it exports both ssb, so the ! matters. Output is -----BEGIN PGP PRIVATE KEY BLOCK----- (armour, not base64). |
signing-key.md:22 |
CI signs with --local-user "$SUBA!" --clearsign |
signature made by subkey A; gpgv Good signature ✓ |
signing-key.md:28 |
gpg --quick-set-expire "$FPR" 2y "$SUBA" |
✓. CI then needs the refreshed public key (see Should fix). |
signing-key.md:29,39 |
gpg --quick-add-key "$FPR" ed25519 sign 2y |
✓ |
signing-key.md:38 |
gpg --edit-key "$FPR" → key 1 → revkey → save (driven by --command-fd) |
subkey A validity r ✓ |
signing-key.md:41 |
gpg --export --export-options export-minimal "$FPR" > montimage-archive-keyring.gpg |
✓ (pub + all subkeys) |
signing-key.md:51-52 |
$GNUPGHOME/openpgp-revocs.d/<FPR>.rev |
path ✓. The file is :-guarded (see Should fix). |
README.md:24 |
gpg --show-keys <keyring> |
✓. It shows the primary fingerprint. |
README snippets
bash -non the twoshblocks: OK.- I also ran them in
debian:bookwormandubuntu:22.04with--network none.curlwas stubbed to a local file,sudoran as root, andURIswas set tofile:/repo; everything else was verbatim.- The
teeinstall wrote/etc/apt/keyrings/mmt.gpgwith mode 644. - With the
.sourcesstanza (Suites:set toVERSION_CODENAME,Signed-By),apt-get updateverified anInReleasesigned by subkey A ✓. - The rotation and revocation cases are under Must fix 3–4.
- The
Local CI
I ran every run: step of ci.yml as bash -e on a scratch clone at 6cb8c6c, with its own RUNNER_TEMP.
- The amd64 archives were downloaded and checksum-checked exactly as written.
- For execution only, the arm64 builds of the same versions (verified against upstream digests) were swapped in, because the host is aarch64.
| Check | Result |
|---|---|
actionlint 1.7.12, no file args, -shellcheck 0.11.0 |
exit 0 on the PR. A planted new.yaml with an untrusted ${{ github.event.issue.title }} is reported, so new workflows are found. |
shellcheck on tracked .sh files |
none tracked, so it skips with a message. With a b.sh and tools.sh planted, both are passed separately, and the SC2086 finding fails the step (rc 123). |
.deb guard |
a planted, force-added pool/main/x_1.0_amd64.deb gives ERROR: .deb files must not be tracked in git and exit 1 ✓. .gitignore blocks a plain git add. |
| Extraction | only into $RUNNER_TEMP. git status shows README.md and docs/ untouched; only the two downloaded archives are untracked. |
Supply chain: re-verified
| Item | Pinned | Upstream | Match |
|---|---|---|---|
actions/checkout v7.0.1 (ci.yml:18, pages.yml:24) |
3d3c42e5aac5ba805825da76410c181273ba90b1 |
tag → commit 3d3c42e5…; this is the latest release |
✓ |
actions/upload-pages-artifact v5.0.0 (pages.yml:27) |
fc324d3547104276b827a68afc52ff2a11cc49c9 |
tag → commit fc324d35…; latest |
✓ |
actions/deploy-pages v5.0.1 (pages.yml:30) |
368f82528645a54fb793d4d04e342629a3f51346 |
tag → commit 368f8252…; latest |
✓ |
actionlint_1.7.12_linux_amd64.tar.gz (ci.yml:26) |
8aca8db9…49a3d8 |
matches upstream checksums.txt, the GitHub asset digest and a local sha256sum |
✓ |
shellcheck-v0.11.0.linux.x86_64.tar.xz (ci.yml:38) |
8c3be12b…227198 |
matches the GitHub asset digest and a local sha256sum |
✓ |
Every uses: is GitHub-owned and SHA-pinned. Every curl uses -fsSL, and there is no curl | sh.
Hygiene
- AI trailers: none in the 8 commit messages or the PR body. There is no
Co-Authored-Byand no "Generated with". - Secrets: none. There is no
BEGIN PGP,PRIVATE KEYor token pattern in the text diff, and no.gpg,.asc,.key,.revor.debfile is tracked. - Stray files: one, the
actionlintbinary (Must fix 1). The other 8 files are the expected ones. - PR title: a Conventional Commits title (
chore:). Repo settings allow only squash merges, using the PR title and body. - Workflows:
- permissions are set at workflow and job level;
pages: writeandid-token: writeare only on thedeployjob (environment: github-pages,mainonly);persist-credentials: falseis set everywhere;- no workflow uses
pull_request_target.
Branch ruleset (unchanged)
main protection still has no required_status_checks rule. After merge, add the context lint from the GitHub Actions integration (id 15368). Do not require deploy: it never runs on a PR.
Uncertainty
- I wrote the apt behaviour tests myself. They used
file:URIs in containers rather than the real Pages URL over HTTPS, but signature checking is the same. - Whether the site is reachable at montimage.github.io/packages can only be checked after merge.
- I reviewed the diff myself, without a separate reviewer subagent.
Third review: PR #3, chore: bootstrap the packages repository and its Pages site (#1)Verdict: WARN Reviewed head All 5 Must fix items from the second review are fixed, and so are 9 of the 10 Should fix items (the tenth is mostly fixed). I re-ran the GnuPG and apt checks for every doc claim that changed, and the new claims hold. Nothing blocks the merge. The verdict is WARN rather than PASS because of a few small leftovers. The most visible one: the new
Must fix from the second review
Should fix from the second review
GnuPG checks (re-run where the doc changed)These ran in throwaway
apt checks (README flow, re-run)These ran in
This confirms that the doc's new claim (users must download the keyring again) is correct, and that the old claim (users refresh automatically) was wrong. Regression checks
PR body (used by the squash)The body is accurate except for one phrase. In the file table, the Branch ruleset
After merge, add the required context Acceptance criteria (#1)
Leftovers for a follow-up issue (non-blocking)
Uncertainty
|
dev-montimage
left a comment
There was a problem hiding this comment.
Third independent review (Claude Code issue-pr-review at 0ddb825): WARN, no blocking findings; all must-fix items of the earlier reviews verified fixed, GnuPG and apt claims re-tested in containers. CI lint green. Leftovers go to a follow-up issue; the package-name leftover is not valid (the Release .deb control field is Package: mmt-dpi).
Summary
Bootstraps the
packagesrepository: signed APT repository for MMT tools.Files changed
README.mdAGENTS.mdCLAUDE.mddocs/signing-key.md.github/workflows/pages.yml.github/workflows/ci.ymlsite/index.html.gitignore*.deb, binaries, and tarballsAcceptance criteria
.sourcesfile withSigned-By, neverapt-key), and the signing-key fingerprint placeholder (TBD)..debfile is ever committed to git; the signing secret is used only in theapt-signingenvironment and is never printed; actions are pinned by full SHA; no AI co-author trailers.Notes
checksums.txt(64-char hash).*.shfiles (skips with message when none); actionlint runs with-shellcheckagainst all workflows.APT_SIGNING_FINGERPRINTis a variable (not a secret), holding subkey A's fingerprint with!suffix.Closes #1