Skip to content

chore: bootstrap the packages repository and its Pages site (#1) - #3

Merged
luongnv89 merged 9 commits into
mainfrom
improvement/1-bootstrap-repo
Nov 11, 2026
Merged

luongnv89 merged 9 commits into
mainfrom
improvement/1-bootstrap-repo

Conversation

@luongnv89

@luongnv89 luongnv89 commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Bootstraps the packages repository: signed APT repository for MMT tools.

Files changed

File Purpose
README.md Repository description, URL, retention, usage instructions, key model
AGENTS.md Agent conventions: no .deb in git, pinned SHAs, no secrets committed
CLAUDE.md Points to AGENTS.md for project conventions
docs/signing-key.md Key model, CI secrets/variables, rotation and revocation procedures
.github/workflows/pages.yml Pages deploy (push to main + workflow_dispatch) with pinned actions
.github/workflows/ci.yml PR CI: actionlint + shellcheck with SHA256-verified tarballs
site/index.html Placeholder index linking to mmt-dpi#24
.gitignore Ignores *.deb, binaries, and tarballs

Acceptance criteria

  • README states what the repository serves, the URL, the retention (last 2 mmt-dpi releases), how users add it (deb822 .sources file with Signed-By, never apt-key), and the signing-key fingerprint placeholder (TBD).
  • AGENTS.md and CLAUDE.md state: no .deb file is ever committed to git; the signing secret is used only in the apt-signing environment and is never printed; actions are pinned by full SHA; no AI co-author trailers.
  • docs/signing-key.md documents the key model, the CI secret names, rotation and revocation, and contains no secret.
  • A Pages workflow (actions/upload-pages-artifact and actions/deploy-pages, pinned) deploys a placeholder index that is reachable at https://montimage.github.io/packages.
  • CI on pull requests runs shellcheck and a workflow linter (actionlint) with a pinned tool version.

Notes

  • actionlint: the tarball is verified against a pinned sha256 from upstream checksums.txt (64-char hash).
  • shellcheck: the tarball is verified against a pinned sha256 (computed from release asset; no upstream checksums file published).
  • Shellcheck runs only on tracked *.sh files (skips with message when none); actionlint runs with -shellcheck against all workflows.
  • Signing key fingerprint is TBD (placeholder in docs/signing-key.md#fingerprint).
  • APT_SIGNING_FINGERPRINT is a variable (not a secret), holding subkey A's fingerprint with ! suffix.

Closes #1

@luongnv89

luongnv89 commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor Author

Review — PR #3: bootstrap: initial repo with Pages site, CI, and docs (#1)

Verdict: FAIL

Reviewed head da5fc0888795f3976c19b32ab0f627b0a3034ef6 against main (d4f7746). This was a review-only pass: nothing was fixed, committed, approved or merged.

The supply chain and workflow security checks pass. The PR fails for two reasons:

  • AC 3 is not met. docs/signing-key.md has no revocation procedure. Its rotation steps also contradict the offline-primary key model.
  • Docs disagree with the key model and the repo settings in three places: the README, AGENTS.md and the secrets table.

There is also a latent CI bug: the shellcheck step breaks as soon as a second .sh file is added.

Leg Result
Spec ac: fail (AC 3), correctness: partial, safety: pass
Standards traceability: pass (Closes #1), maintainability: partial
CI lint passed on da5fc08… (GitHub Actions, app id 15368)
Local actionlint 1.7.12 + shellcheck 0.11.0 exit 0 on both workflows

Must fix

  1. docs/signing-key.md: there is no revocation procedure (AC 3). The "Rotation and revocation" section only describes rotation. It should cover:
    • where the primary key's revocation certificate is kept;
    • how to revoke subkey A (gpg --edit-key <primary> → key N → revkey);
    • how to republish the revoked public key on Pages;
    • what users have to do;
    • what happens if subkey B or the primary key is compromised.
  2. docs/signing-key.md: the rotation steps contradict the key model.
    • Step 1, "Generate a new primary key pair offline", throws away the offline primary key on every rotation. A routine rotation should keep the primary key and add a new subkey A with gpg --quick-add-key <primary-fpr> <algo> sign <expiry>.
    • Step 2, "Derive a new subkey A and publish it to the APT repository", and step 4 say the same thing.
    • Step 5, "until the next 2 release cycle has passed", is garbled.
    • The steps never say to update APT_SIGNING_FINGERPRINT.
    • Subkeys are not "derived" from the primary key. They are generated and certified by it.
  3. docs/signing-key.md: APT_SIGNING_FINGERPRINT is listed as a secret. It sits in the "CI secrets" table under the column "Secret". Issue Bootstrap the packages repository and its Pages site #1 makes it a variable (vars.APT_SIGNING_FINGERPRINT) in apt-signing, so it needs its own "Variables" row.
    • The doc should also say which fingerprint the variable holds. It currently says "primary key". To force signing with subkey A, it needs subkey A's fingerprint with a ! suffix.
  4. docs/signing-key.md: the export command for APT_SIGNING_KEY is missing. The doc should state that the secret is made with gpg --armor --export-secret-subkeys <subkeyA-fpr>!. Exporting with --export-secret-keys would put the offline primary key into CI.
  5. README.md:9: the README says the index is "signed with an offline primary key". That is wrong under this key model: the APT index is signed by subkey A, and the primary key stays offline.
  6. AGENTS.md:27: the environment name is wrong. It says "The pages environment is limited to main". The environment is github-pages, as in pages.yml and the repo settings.
  7. .github/workflows/ci.yml:58: ./shellcheck --severity=error "$SH_FILES" passes every file as one newline-joined argument. I reproduced it with two files: shellcheck exits 2 with openBinaryFile: does not exist. Commit da5fc08 introduced this. It is invisible today only because the repo has no .sh files. Use git ls-files -z '*.sh' | xargs -0 -r ./shellcheck, and consider dropping --severity=error, which hides warnings.
  8. .github/workflows/ci.yml:33,46: the tool tarballs are extracted into the checkout root. The actionlint tarball contains README.md and docs/*.md, so tar xzf overwrites the repo's README.md and writes files into docs/. Extract only the binary into $RUNNER_TEMP, for example tar xzf … -C "$RUNNER_TEMP" actionlint.

Should fix (non-blocking)

  • The docs overstate what actionlint covers. ci.yml:50 lists two workflow files by hand, so a future workflow (such as the APT publish workflow) will not be linted. Yet AGENTS.md:21 and README.md:43 say actionlint runs on "all / every" workflow file. Run ./actionlint -shellcheck ./shellcheck with no file arguments; it finds all workflows itself, and I checked that this exits 0 locally.
  • ci.yml:26 downloads actionlint_1.7.12_checksums.txt and never uses it. The hard-coded constant is what gets verified, which is fine. The PR body's claim "SHA256 verified against actionlint_1.7.12_checksums.txt" is therefore inaccurate. Either drop the download or check against the file as well.
  • The pages.yml deploy job gives no contents permission. Job-level permissions replaces the workflow-level contents: read. Checkout works today only because the repo is public. Add contents: read to the job. Also consider concurrency: { group: pages, cancel-in-progress: false }.
  • The README sets up a Signed-By keyring path but never says how to get the key. It should explain how to obtain the key and verify its fingerprint. Debian recommends /etc/apt/keyrings/ for keys an admin installs; /usr/share/keyrings is for keys that packages install. Suites: stable / Components: main also commits to a layout the publish workflow must match, so record that as a decision.
  • CLAUDE.md does not repeat the signing-secret rule. Issue Bootstrap the packages repository and its Pages site #1 says CLAUDE.md should state that the secret is used only in apt-signing and never printed. CLAUDE.md points to AGENTS.md, which has the rule, but its own short list leaves it out. Add one line.
  • The .deb rule has no guard. Consider a .gitignore with *.deb and a CI step that fails when git ls-files '*.deb' returns anything.
  • site/index.html link contrast is low. The link colour #b8860b on white is about 3.25:1, below the WCAG AA threshold of 4.5:1.
  • The PR title type bootstrap: is not a Conventional Commits type. The squash commit takes the PR title. Consider chore: or feat:.

Acceptance criteria (#1)

# Criterion Status Evidence
1 README: what it serves, URL, retention, deb822 .sources + Signed-By, no apt-key, fingerprint partial All of these are present, and the deb822 stanza is valid. Two gaps: the signer is described wrongly (Must fix 5), and there is no step for getting the key. The fingerprint is deferred, which is acceptable.
2 AGENTS.md + CLAUDE.md: no .deb; secret only in apt-signing, never printed; full-SHA pins; no AI trailers partial AGENTS.md covers all four rules but has the wrong environment name (Must fix 6). CLAUDE.md leaves out the signing-secret rule.
3 signing-key.md: key model, CI secret names, rotation and revocation, no secret fail There is no revocation procedure, the rotation steps contradict the model, and the fingerprint is listed as a secret instead of a variable (Must fix 1–3). The doc contains no secret, and the fingerprint is a TBD placeholder as expected.
4 Pinned Pages workflow deploys a placeholder that is reachable at montimage.github.io/packages pass (pre-merge) The workflow is correct, and Pages build_type is workflow. Reachability can only be checked after merge, because the workflow runs only on pushes to main.
5 PR CI runs shellcheck + actionlint at pinned versions pass Both tools are pinned and checksum-verified, and lint is green. The shellcheck step has a latent bug (Must fix 7).

Supply chain — verified

Item Pinned Upstream Match
actions/checkout v7.0.1 3d3c42e5aac5ba805825da76410c181273ba90b1 lightweight tag → commit 3d3c42e5… ✓
actions/upload-pages-artifact v5.0.0 fc324d3547104276b827a68afc52ff2a11cc49c9 lightweight tag → commit fc324d35… ✓
actions/deploy-pages v5.0.1 368f82528645a54fb793d4d04e342629a3f51346 lightweight tag → commit 368f8252… ✓
actionlint_1.7.12_linux_amd64.tar.gz 8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8 matches the line in upstream checksums.txt, the GitHub asset digest, and a local sha256sum ✓
shellcheck-v0.11.0.linux.x86_64.tar.xz 8c3be12b05d5c177a04c29e3c78ce89ac86f1595681cab149b65b97c4e227198 matches the GitHub release asset digest and a local sha256sum (upstream publishes no checksum file) ✓
  • All three tags are each action's latest release.
  • Every uses: is GitHub-owned. The repo allows only GitHub-owned actions and requires SHA pinning.
  • Every curl call uses -fsSL, and there is no curl | sh.

Workflow security — verified

  • permissions: is set at both workflow and job level, and the default token is read-only.
  • pages: write and id-token: write appear only on the deploy job, which uses environment: github-pages. That environment is restricted to the main branch.
  • Both checkout steps set persist-credentials: false.
  • No workflow uses pull_request_target.
  • pages.yml triggers only on push to main and on workflow_dispatch. CI triggers only on pull_request to main.
  • The artifact path is site/.
  • Local actionlint 1.7.12 with shellcheck 0.11.0 (arm64 builds, checked against upstream checksums) exits 0 on both workflows.

Hygiene — verified

  • No commit message and nothing in the PR body contains a Co-Authored-By line or a "Generated with" footer.
  • No .deb, key, .gpg or .asc files are tracked, and there is no BEGIN PGP, PRIVATE KEY or token pattern.
  • There are no stray files; exactly 7 files changed.
  • site/index.html is valid and static:
  • Repo settings allow squash merges only, using the PR title and PR body.

Branch ruleset

Ruleset main protection (id 26959023) has no required_status_checks rule yet.

  • Add: context lint from the GitHub Actions integration (integration_id 15368). This is the lint job of workflow CI, and it is the only check that runs on pull requests.
  • Do not require deploy from the Pages workflow. It runs only on pushes to main, so it never reports on a PR and would block every merge.
  • If the lint job is ever renamed, update the ruleset in the same PR.

Uncertainty

  • Whether the site is reachable at https://montimage.github.io/packages can only be checked after merge.
  • No full HTML validator (tidy or the W3C validator) was available. I checked the markup structure with a parser instead.

@luongnv89 luongnv89 changed the title bootstrap: initial repo with Pages site, CI, and docs (#1) chore: bootstrap the packages repository and its Pages site (#1) Nov 10, 2026
@luongnv89

Copy link
Copy Markdown
Contributor Author

Re-review: PR #3, chore: bootstrap the packages repository and its Pages site (#1)

Verdict: FAIL

Reviewed head 6cb8c6c1ac564c0003d739ec810426da794d129c against main (d4f7746). The previous review was at da5fc08. This was a review-only pass: nothing was fixed, committed, pushed, approved or merged.

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:

  • New problem: the last commit adds a 5.8 MB aarch64 actionlint binary at the repo root.
  • Docs that are still wrong: some of the new rotation and revocation text is incorrect. I checked this with apt in Debian 12 and Ubuntu 22.04 containers:
    • users do not "refresh automatically";
    • after a subkey A rotation, nothing tells you to update the CI secret;
    • the keyring file name in the README does not match the published name.
Leg Result
Spec ac: partial (AC 1, AC 3), correctness: fail, safety: partial
Standards traceability: pass (Closes #1; the title is Conventional Commits), maintainability: fail (a committed binary)
CI lint passed on 6cb8c6c1… (run 42854990480)
Local CI every ci.yml step reproduced; all 4 checks behave as intended (see Local CI)

Previous items: status

Must fix (from da5fc08)

# 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

  1. actionlint (repo root): a 5.8 MB compiled binary is committed. Commit 6cb8c6c added it.

    • It is the upstream actionlint 1.7.12 linux_arm64 binary: its sha256 ac032343…beb60 matches the one in actionlint_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 main for good, and CI uses its own copy in $RUNNER_TEMP anyway.
    • 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.
  2. README.md:17: the keyring URL uses the wrong file name. The README downloads …/packages/mmt-archive-keyring.gpg. docs/signing-key.md:41 and the maintainer procedure (§3, line 58) both produce montimage-archive-keyring.gpg, so the README URL will return 404. Use one name everywhere. The local path /etc/apt/keyrings/mmt.gpg can stay as it is, but consider montimage-archive-keyring.gpg there too.

  3. docs/signing-key.md:43: "Users refresh automatically on the next apt update" is false. apt never fetches keys: the Signed-By file is whatever the user downloaded. I checked this in debian:bookworm and ubuntu:22.04 containers 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 gives NO_PUBKEY for the extended subkey; the refreshed keyring gives GOODSIG.

    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-keyring package so that apt updates the key itself.

  4. 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 update APT_SIGNING_KEY, APT_SIGNING_PASSPHRASE and APT_SIGNING_FINGERPRINT (procedure steps 3–5). The previous item 2 asked for the APT_SIGNING_FINGERPRINT update, and it is still missing.

  5. 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 --passwd there, and only then re-exports.
    • Document that step, or link to it.
    • Also, --armor output is ASCII-armoured, not "Base64-encoded". The procedure stores the .asc file as it is (gh secret set … < apt-signing-subkey.asc). If "Base64-encoded" stays, the future publish workflow may end up decoding it twice.

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, $SUBA and N are never defined. Say that FPR is the primary key's fingerprint, SUBA is subkey A's, and that N is the subkey's index in the --edit-key listing.
    • :28 extends 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 only site/ (pages.yml:29), so the doc should say site/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-dpi debian/upstream/signing-key.asc.
  • docs/signing-key.md:51: "Publish the revocation certificate" needs the how-to. The .rev file is guarded: line 21 is :-----BEGIN PGP PUBLIC KEY BLOCK-----. Remove the leading :, run gpg --import <FPR>.rev, then re-export the keyring into site/.
  • 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 with Unusable secret key once 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 imports site/montimage-archive-keyring.gpg before 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 da5fc08 README said "will be published once the maintainer creates it", and that line is gone. Link to docs/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 use sudo install -m 0644 <tmpfile> /etc/apt/keyrings/….
    • gpg: stock debian:bookworm and ubuntu:22.04 images have no gpg, only gpgv. Mention sudo apt-get install gnupg.
    • Directory: /etc/apt/keyrings exists on both images, but sudo install -d -m 0755 /etc/apt/keyrings is a cheap guard.
  • ci.yml:25,37: the archives are still downloaded into the checkout. It is harmless, because the .deb guard uses git ls-files. To keep the workspace clean, cd "$RUNNER_TEMP" before curl -fsSLO.
  • AGENTS.md:21: "shellcheck and actionlint on all .github/workflows/*.yml files" is not accurate. Shellcheck runs on tracked *.sh files and, through actionlint, on run: blocks. Actionlint also lints .yaml files.
  • PR body:
    • The file table leaves out the actionlint binary.
    • "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.

For the maintainer (outside this PR)

These are in the maintainer's offline signing-key procedure:

  • Line 102 sets APT_SIGNING_FINGERPRINT to "<SUBA>" with no !. The key model you gave and docs/signing-key.md:22 both 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 -n on the two sh blocks: OK.
  • I also ran them in debian:bookworm and ubuntu:22.04 with --network none. curl was stubbed to a local file, sudo ran as root, and URIs was set to file:/repo; everything else was verbatim.
    • The tee install wrote /etc/apt/keyrings/mmt.gpg with mode 644.
    • With the .sources stanza (Suites: set to VERSION_CODENAME, Signed-By), apt-get update verified an InRelease signed by subkey A ✓.
    • The rotation and revocation cases are under Must fix 3–4.

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-By and no "Generated with".
  • Secrets: none. There is no BEGIN PGP, PRIVATE KEY or token pattern in the text diff, and no .gpg, .asc, .key, .rev or .deb file is tracked.
  • Stray files: one, the actionlint binary (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: write and id-token: write are only on the deploy job (environment: github-pages, main only);
    • persist-credentials: false is 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.

@luongnv89

Copy link
Copy Markdown
Contributor Author

Third review: PR #3, chore: bootstrap the packages repository and its Pages site (#1)

Verdict: WARN

Reviewed head 0ddb825f2a1a05d4998ea804fe7adce2e0b7299c against main (d4f7746). The previous review was at 6cb8c6c. This was a review-only pass: nothing was fixed, committed, pushed, approved or merged.

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 README.md:48 installs a package called mmt-dpi, but mmt-dpi does not build a package with that name. The leftovers are listed at the end, ready for a follow-up issue.

Leg Result
Spec ac: pass (AC 4 can only be checked after merge), correctness: partial (leftovers below), safety: pass
Standards traceability: pass (Closes #1; the title is Conventional Commits), maintainability: pass
CI lint passed on 0ddb825f… (run 42857931163, GitHub Actions app 15368). The log shows actionlint ran and shellcheck skipped because no .sh files are tracked.
Squash content 8 files, +356/−1, no binary (git diff --numstat main 0ddb825 lists no binary file)

Must fix from the second review

# Item Status Evidence
1 Committed actionlint binary fixed git diff 6cb8c6c..0ddb825 deletes it (Bin 5832866 -> 0 bytes). git ls-files lists only the 8 expected files. .gitignore:2-5 adds /actionlint, /shellcheck*, *.tar.gz and *.tar.xz. The binary is still in the branch history, but squashing leaves it out of main.
2 Keyring file name differs between files fixed montimage-archive-keyring.gpg is now the only name. It is used in the download URL (README.md:19), the temp file (:20, :28), the installed file (:28) and Signed-By (:41). In the doc, the export is at docs/signing-key.md:55 and the published path is always site/montimage-archive-keyring.gpg (:56, :60, :78, :91, :107). git grep finds no mmt.gpg or mmt-archive-keyring left. Pages publishes site/ (pages.yml:29), so the README URL matches the published file.
3 "Users refresh automatically" is false fixed The claim is gone. docs/signing-key.md:93-94 now says "After every key change … users must download the keyring again (apt does not update it by itself)", and README.md:51-52 says the same. I checked this again in containers (see apt checks). Leftover: :93-94 sits under Subkey A compromised, and the Expiry extension section (:48-62) has no step for users.
4 A new subkey A means new CI values fixed docs/signing-key.md:64-79 adds a "replaces CI secrets" section. Step 4 (:73-75) replaces APT_SIGNING_KEY, APT_SIGNING_PASSPHRASE and APT_SIGNING_FINGERPRINT ("new fingerprint with !"). The revocation steps (:87-89) replace all three. The "CI secrets do not change" note now applies only to expiry extension (:48, :59).
5 The export recipe puts the primary key's passphrase into CI; it says "Base64" fixed docs/signing-key.md:27 says "ASCII-armoured export … re-protected". :28 says "CI-only passphrase set on the re-protected export". :31-44 adds the temporary-GNUPGHOME + --passwd + re-export recipe and says the re-protected file goes into APT_SIGNING_KEY. Tested: it works (see GnuPG checks). Two leftovers: :33 never writes apt-signing-subkey.asc, the file :38 imports; and --passwd exits 2 with an error about the stub primary key, which the doc does not mention.

Should fix from the second review

# Item Status Evidence
1 "step 3 below" points nowhere fixed The export is now inline at docs/signing-key.md:54-55.
2 $FPR, $SUBA, N undefined; only A extended fixed :16-21 defines FPR, SUBA, SUBB and N. :52-53 extends "$SUBA" "$SUBB" (tested: both expiries change).
3 Pages path missing fixed site/montimage-archive-keyring.gpg at :56, :78, :91 and :107.
4 Subkey B also needs a republish here fixed :77-79 and :99-100.
5 How to publish the revocation certificate fixed :104-106: remove the leading :, then gpg --import. Tested. The unedited .rev gives no valid OpenPGP data found; the edited one marks the primary key [revoked] in the exported keyring. Leftover: the "kept offline" wording was dropped, and nothing says to keep a copy of the .rev away from the drive (see leftovers).
6 Expiry extension needs CI to import the public key fixed :59-62.
7 README install: fingerprint, order, gnupg, directory fixed gnupg: README.md:17. Directory: :18. Download to a temp file and verify: :19-20. Fingerprint: a link to docs/signing-key.md#fingerprint, which is TBD (:23-25; the anchor matches ## Fingerprint at docs/signing-key.md:112). Install after verifying: :28 (mode 644, root). Tested in containers.
8 Archives downloaded into the checkout fixed ci.yml:25 and :38 now cd "$RUNNER_TEMP" before curl -fsSLO. (-C "$RUNNER_TEMP" at :33/:46 is now redundant but harmless.)
9 AGENTS.md CI wording fixed AGENTS.md:21-24 is accurate. README.md:68 still uses the old loose wording, "shellcheck and actionlint on every workflow file" (nit).
10 PR body accuracy mostly fixed The binary is gone, so the file table is complete. The Notes say the tarball is verified, and the AC 1 fingerprint placeholder is now true (README.md:23-25). Leftover: the ci.yml row still says "SHA256-verified binaries"; it is the tarballs that get verified.

GnuPG checks (re-run where the doc changed)

These ran in throwaway GNUPGHOMEs under the scratchpad, with GnuPG 2.4.4. The test key was test@example.invalid: ed25519, certify-only, 5 years, with two signing subkeys of 2 years. The primary passphrase was a test value. No real key was touched. Passphrases came from a test pinentry, so the doc's interactive commands ran as written.

Doc line Command Result
:33 gpg --armor --export-secret-subkeys "$SUBA!" -----BEGIN PGP PRIVATE KEY BLOCK----- (armoured ✓). The primary passphrase is needed.
:37-38 mktemp -d, chmod 700, --batch --import apt-signing-subkey.asc rc 0: public key and secret key imported
:39 gpg --homedir "$T" --passwd "$FPR" Prompts: unlock (old passphrase), then a new passphrase. The subkey is re-protected ✓, but gpg prints error changing passphrase: No secret key for the stub primary key and exits 2.
:40 --armor --export-secret-subkeys "$SUBA!" from $T rc 0. The export asks for the new passphrase. -K shows sec# (stub) and one ssb.
CI side fresh GNUPGHOME, import the re-protected file, --local-user "$SUBA!" --clearsign The primary passphrase gives Bad passphrase. The CI passphrase gives a signature by subkey A, and gpgv reports Good signature ✓
:53 --quick-set-expire "$FPR" 2y "$SUBA" "$SUBB" rc 0: both subkey expiries move, the primary is unchanged ✓
:55/:57 --export --export-options export-minimal committed as mmt-dpi signing-key.asc The export is binary while the file name says armoured. gpg --dearmor passes it through unchanged, so it probably works, but --armor would match the name (nit).
:104-106 strip : from the .rev, gpg --import, re-export pub … [C] [revoked: …] ✓

apt checks (README flow, re-run)

These ran in debian:bookworm and ubuntu:22.04. sudo was a no-op (the container ran as root). README :19's curl was replaced by a copy of the test keyring, because the site is not live yet. URIs pointed to a local file: repo, Suites was set to VERSION_CODENAME, and everything else was verbatim.

Step Debian 12 Ubuntu 22.04
Stock image has gpg no no (so :17 is needed ✓)
README.md:17 verbatim on a stock image rc 100: there are no apt lists until apt-get update (only matters in containers) rc 100
:17 after apt-get update, then :18, :20, :28 ✓ The fingerprint is shown; the key is installed with mode 644, owned by root ✓
apt-get update, repo signed by subkey A rc 0 rc 0
CI moves to a new subkey A2, user keeps the old keyring rc 100, NO_PUBKEY AB4A4D7C62E715EF, "is not signed" rc 100
User downloads the keyring again (README.md:51-52) rc 0 rc 0

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

  • Action pins (unchanged): every uses: is GitHub-owned and pinned by full SHA, and each SHA is the commit of its tag:

    • actions/checkout v7.0.1 = 3d3c42e5…
    • actions/upload-pages-artifact v5.0.0 = fc324d35…
    • actions/deploy-pages v5.0.1 = 368f8252…

    Each is the latest release.

  • Checksums (unchanged):

    • actionlint 8aca8db9…49a3d8 matches upstream checksums.txt.
    • shellcheck 8c3be12b…227198 matches the GitHub asset digest.
  • Permissions (unchanged):

    • contents: read is set at workflow and job level.
    • pages: write and id-token: write are only on the deploy job.
    • persist-credentials: false is set everywhere.
    • No workflow uses pull_request_target.
    • Both the apt-signing and github-pages environments are limited to the main branch, which matches AGENTS.md:30-31.
  • Secrets / .deb: there is no BEGIN PGP, PRIVATE KEY or token pattern in the squash diff. No .deb, .gpg, .asc, .key, .rev or .pgp file is tracked.

  • AI trailers: none in the 9 commit messages or in the PR body.

PR body (used by the squash)

The body is accurate except for one phrase. In the file table, the ci.yml row says "SHA256-verified binaries", but it is the tarballs that are verified; the Notes already say so. It is cosmetic and can be fixed at merge time. Closes #1 is present.

Branch ruleset

main protection (id 26959023, active) has deletion, non_fast_forward, required_linear_history and pull_request. It still has no required_status_checks rule.

After merge, add the required context lint, with the integration GitHub Actions (app id 15368). That is the only check that runs on pull requests, and it passed at 0ddb825. Do not require deploy: it never runs on a PR.

Acceptance criteria (#1)

# Criterion Status Evidence
1 README: what it serves, URL, retention, deb822 .sources + Signed-By, never apt-key, the fingerprint once it exists pass README.md:3-10, :33-45, :23-25 (the TBD link). The deb822 stanza works in both containers.
2 AGENTS.md + CLAUDE.md rules pass AGENTS.md:7-17, CLAUDE.md:7-12
3 signing-key.md: key model, secret names, rotation and revocation, no secret pass docs/signing-key.md:3-29, :46-79, :81-110. Tested above.
4 A pinned Pages workflow deploys a placeholder at montimage.github.io/packages pass (pre-merge) pages.yml. Reachability can only be checked after merge.
5 PR CI runs shellcheck + actionlint at pinned versions pass ci.yml:22-67, CI green

Leftovers for a follow-up issue (non-blocking)

  1. README.md:48: sudo apt-get install mmt-dpi names a package that does not exist. mmt-dpi's debian/control (default branch) has Source: mmt-dpi and binary packages libmmt-dpi1 and libmmt-dpi-dev. apt installs binary packages, so this command fails with "Unable to locate package". Use the real names, or align with the packaging work in Add apt/deb package support for mmt-dpi mmt-dpi#24.
  2. docs/signing-key.md:33: the export command does not write a file. Add > apt-signing-subkey.asc, so that :38 has a file to import.
  3. docs/signing-key.md:39: warn that the error is expected. Say that --passwd prints error changing passphrase: No secret key for the stub primary key and exits 2, and that this is expected; the subkey is still re-protected. Otherwise a maintainer may stop there, or a set -e script will.
  4. docs/signing-key.md:64-79: say which fingerprint SUBA holds. Before running the recipe for the new subkey, set SUBA to the new subkey's fingerprint (gpg --list-keys --with-subkey-fingerprints "$FPR"). For subkey B, the recipe and file names need the B equivalents.
  5. docs/signing-key.md:93-94: the "users must download the keyring again" line sits under Subkey A compromised. Move it to a section that covers every key change, or repeat it in Expiry extension (:48-62) and Adding a new subkey (:64-79).
  6. docs/signing-key.md:104-106: keep a copy of the .rev file away from the drive. If the primary key is lost, the .rev file under that same $GNUPGHOME is probably lost with it. Say to keep a copy apart from the drive, and on a fresh machine to import the published keyring before importing the .rev.
  7. docs/signing-key.md:55-57: export the mmt-dpi file armoured. mmt-dpi's file is signing-key.asc, so export it with --armor.
  8. README install snippet:
    • Add sudo apt-get update before :17, because stock images have no apt lists.
    • Use mktemp instead of the fixed /tmp/montimage-archive-keyring.gpg.
  9. Wording:
    • README.md:68 should match AGENTS.md:21-24.
    • In the PR body, change "SHA256-verified binaries" to "SHA256-verified tarballs".

Uncertainty

  • The apt tests used local file: repos in containers, not the real Pages URL over HTTPS; signature checking is the same. The curl download in README.md:19 was not run, because the site is not live yet.
  • Whether the site is reachable at montimage.github.io/packages can only be checked after merge.
  • The package-name finding (leftover 1) is based on mmt-dpi's current default branch. The packaging in mmt-dpi#24 may add a mmt-dpi binary package later.
  • I did the review myself, without a separate reviewer subagent.

@dev-montimage dev-montimage left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@luongnv89
luongnv89 merged commit 4f2b354 into main Nov 11, 2026
1 check passed
@luongnv89
luongnv89 deleted the improvement/1-bootstrap-repo branch November 11, 2026 17:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Bootstrap the packages repository and its Pages site

2 participants