[ErenAri]

Draft. Merge only on an exact-head operator decision. Documentation only, plus action.yml description strings. No behaviour change.

Why

An independent documentation review against the shipped code found:

• MD-2, security docs: the manual verification commands were weaker than the installer's tag binding.
  • The README container check used an unanchored --certificate-identity-regexp github.com/Kernel-Guard/bpfcompat, which accepts any identity containing that substring.
  • The blob checks used @refs/tags/v regexps, which accept any release's signature.
  • Some gh attestation verify examples lacked --signer-workflow, and none had --source-ref.
• MD-1: several docs on main described behaviour from later releases in the present tense, while the README and quickstart pin @v0.3.7. Some of it ships from v0.4.0-rc.2 and v0.3.8-rc.1, and some only from v0.4.0-rc.5.
• MD-4 to MD-7, CP6: gaps and inaccuracies:
  • the release gate list;
  • BPFCOMPAT_DOC_DIR and /usr/libexec/bpfcompat;
  • a stale tag example and an unqualified SBOM signature claim;
  • artifact/binary input descriptions;
  • the asset table missing bpfcompat-linux-arm64;
  • the Action's license-bundle verification.

Changes

• 5d444e7 docs: bind manual verification commands to the exact release tag.
  • Blob signatures use --certificate-identity …/release-artifacts.yml@refs/tags/$VER.
  • Attestations use --signer-workflow and --source-ref "refs/tags/$VER", the flags scripts/install.sh uses.
  • The README container check uses the exact signer for v0.3.7 (ghcr-image.yml@refs/tags/v0.3.7), and the README states the signer per release.
    • The stable 0.3.5 to 0.3.7 images were signed by ghcr-image.yml.
    • Every release-candidate image is signed by release-artifacts.yml: 0.4.0-rc.2 (the first, 2026-07-29), 0.4.0-rc.3, 0.3.8-rc.1, 0.3.8-rc.2 and 0.4.0-rc.4.
    • These were checked against the live signature SANs and attestations.
  • Version qualifiers are added where behaviour is not in v0.3.7: "from v0.4.0-rc.2 and v0.3.8-rc.1" (promotion evidence, SBOM signature, Action attestation verification) and "from v0.4.0-rc.5".
  • The gate list and env reference are completed.
  • Files: README.md, docs/{compatibility-contract,production-support-boundary,quickstart,supply-chain,verifying-releases}.md.
• b9f3aa1 action: document the ./ prefix and workspace binary precedence in inputs. Description strings only. This makes the hosted compatibility gate required on the PR.
• 35d6ebe docs: state the gh minimum and correct when RC verification features began. These are the review follow-ups:
  • gh minimum: gh 2.68.0 or later (--signer-workflow since 2.51.0, --source-ref since 2.68.0). An older gh stops without verifying; use cosign or upgrade. gh 2.97.0 and 2.102.0 fixed published advisories in how these values are matched, so 2.102.0 or later is recommended.
  • Onset: the "From v0.4.0-rc.4" qualifiers are corrected to "from v0.4.0-rc.2 and v0.3.8-rc.1".
  • Image signers: the full release-artifacts.yml list, and the 0.3/latest aliases.
  • BPFCOMPAT_DOC_DIR: the bundle goes to <BPFCOMPAT_DOC_DIR>/<tag>/.
  • Stable-only gates: gates 4–5 are labelled stable-only.
  • Partial downloads: sha256sum -c --ignore-missing where only some assets are downloaded.
  • SBOM attestation: only bpfcompat-linux-amd64 carries one.
  • action.yml: the artifact description also names a localhost first directory.
• 6de1bb7 docs: the v0.3.8 candidates' Action fails without attestation support. These are the second review's follow-ups:
  • Fallback scope: the source-build fallback without gh attestation support applies to the v0.4.0 release candidates. The v0.3.8 candidates' Action fails the job instead.
  • Old gh errors: gh before 2.47.0 reports unknown command "attestation", and before 2.68.0 unknown flag. The boundary was first given as 2.49.0 and is corrected in a follow-up commit; gh 2.47 and 2.48 run the hidden attestation command.

Validation

• make check-docs-drift, scripts/check-doc-pins.sh, make env-docs-check, the freeze check, make check-release-consistency and git diff --check all pass.
• actionlint, run offline from the module cache, passes.
• The Action shell tests pass, including action-diff_test.sh. An earlier failure of action-diff_test.sh in the author's checkout came from a TMPDIR path containing .., not from the code.

Not changed (follow-ups)

• promote-release.yml (lines 179–190 and 222) still verifies with the @refs/tags/v regexp, and scripts/verify-release-assets.sh (used by the Action) has no --source-ref. Both are release tooling, not docs, and are recorded for a separate decision.
• The installer's error message when gh lacks --source-ref is a code change, not part of this PR.
• MD-3 (the stable runbook omits the --require-decided and validator==RC gates in docs/production-release-process.md) is fixed in release: let the stable PR and tag build pass the stable canary-pin and doc-pin checks #266, still an open draft. Merging this PR alone leaves MD-3 open.
• Commit 5d444e7's message still names rc.4 as the onset (corrected in 35d6ebe). It is left unamended so the reviewed heads stay valid.
• There is no CHANGELOG entry, to avoid conflicting with the rc.5 preparation PR release: prepare v0.4.0-rc.5 metadata and an offline, AST-based RC preflight (replaces #264) #265. Suggested line: "Docs: manual release verification (cosign, gh attestation, container) is bound to the exact release tag and signer workflow like the installer (gh 2.68.0 or later), and docs mark which behaviour ships from v0.4.0-rc.2/v0.3.8-rc.1 or v0.4.0-rc.5."

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}