Skip to content

ADR-0014: GitHub Release Assets as the Debian Channel

Date: 2026-10-16

Status

Accepted (2026-10-18)

Supersedes the APT node of the decision diagram (DEB1/DEB2/DEB3 --> APT["Authenticated APT Archive (apt.example.com)"]) and the fourth bullet of decision section 1 ("Published to https://apt.example.com/kernels/ via reprepro with GPG detached signatures.") of ADR-0004, as well as its positive consequence wording ("install .deb packages via apt") only as far as it implies an archive. The rest of ADR-0004 stands, as amended by ADR-0006 and ADR-0009.

Context

ADR-0004 specified a dual packaging architecture delivering native Debian packages (bindeb-pkg) and Unified Kernel Images (systemd-ukify). In its decision diagram and decision section 1, ADR-0004 stated that Debian packages would be published to an authenticated APT repository (https://apt.example.com/kernels/) via reprepro with GPG detached signatures, and its positive consequences stated that cloud golden images would "install .deb packages via apt".

In practice, no reprepro pipeline, no APT repository, and no signed InRelease metadata exist anywhere in the repository (SECURITY.md:88, Verify & Install section 5, Packaging & Delivery section 5.1).

Instead, the actual release and publication mechanism implemented in .github/workflows/publish-release.yml publishes Debian packages as release assets attached directly to GitHub Releases. The step "Publish to GitHub Release" (softprops/action-gh-release) uploads these files from the build output:

  • output/*.deb: Debian packages (linux-image, linux-headers, linux-libc-dev).
  • output/vmlinuz-*: Unpackaged standalone kernel image.
  • output/*.config: Resolved kernel configuration (kernel-<stream>-x86_64.config).
  • output/*.cdx.json: CycloneDX SBOM generated by Syft.
  • output/*.spdx.json: SPDX SBOM generated by Syft.
  • output/*.manifest.json: Downstream artifact manifest (kernel-<stream>.manifest.json).
  • output/SHA256SUMS*: the checksum file and its keyless cosign bundle (SHA256SUMS.bundle, written by cosign sign-blob in .github/workflows/release-build.yml).
  • output/*.provenance.sigstore.json: the build provenance bundle from actions/attest-build-provenance (ADR-0012).

Cryptographic provenance is established keyless: SHA256SUMS is signed using cosign with GitHub Actions OIDC tokens. Downstream consumer cordanaLLM/imago consumes the release manifest (imago.nucleus.kernel-artifact.v1) and verifies the cosign bundle over SHA256SUMS, then verifies the checksum file digest, and finally verifies every per-artifact digest before any image build consumes a kernel (AGENTS.md "The contract with imago", Packaging & Delivery section 5.3). Following publication, the workflow emits a repository_dispatch event of type kernel_release_published to cordanaLLM/imago.

Releases published today are x86_64 only (Verify & Install section 5). The documented installation procedure in Verify & Install consists of downloading assets, verifying cryptographic signatures and checksums, and installing packages with dpkg -i:

gh release download <release-tag> -R cordanaLLM/nucleus
cosign verify-blob --bundle SHA256SUMS.bundle --certificate-identity "https://github.com/cordanaLLM/nucleus/.github/workflows/release-build.yml@refs/tags/<release-tag>" --certificate-oidc-issuer https://token.actions.githubusercontent.com SHA256SUMS
sha256sum -c SHA256SUMS
sudo dpkg -i linux-image-*.deb linux-headers-*.deb

Issue #116 ("ADR-0004 claims an APT archive via reprepro that does not exist") documents this architectural divergence. Because accepted ADR records are immutable history (ADR Overview), a superseding ADR is required to align the recorded architecture with the operational reality.

Decision

  1. GitHub Release Assets as the Debian Channel: GitHub Release assets, accompanied by the keyless cosign-signed SHA256SUMS and the machine-readable artifact manifest kernel-<stream>.manifest.json, are the authoritative publication and distribution channel for Debian packages (linux-image, linux-headers, and linux-libc-dev).

  2. No APT Archive: An APT archive is not part of the architecture. The repository maintains no reprepro configuration, APT repository metadata, or InRelease signing infrastructure. If an APT archive is desired in the future, it must be tracked in its own dedicated issue and evaluated under a separate ADR; no APT repository design or implementation is planned here.

  3. Status of ADR-0004: The rest of ADR-0004 stands, as amended by ADR-0006 (OCI registry namespace for UKI artifacts) and ADR-0009 (kernel compilation, the artifact gate, localversion conventions, and headers package requirements).

Consequences

Positive

  • Unified Release Pipeline: Debian packages are published and cataloged alongside SBOMs, build provenance attestations, and configuration files in a single, atomic release channel.
  • Strict Verification Prior to Ingestion: Downstream consumers (cordanaLLM/imago and workstation administrators) verify cryptographic provenance via cosign signatures and SHA-256 digests before installing packages.
  • Zero Archive Key Management Overhead: Eliminates the operational requirement to create, protect, and rotate long-lived GPG private signing keys, passphrases, or Debian repository infrastructure in CI.

Negative

  • No Native APT Automated Updates: Systems cannot discover or update kernel packages via apt-get update && apt-get upgrade. Consumers must download and verify assets per release or orchestrate installations via downstream automated provisioning tooling.

Neutral

  • UKI Publication Remains Open: Publication of Unified Kernel Images (.efi) remains unreleased, tracked under issue #114.
  • OCI Delivery Path Unchanged: The OCI registry distribution path decided in ADR-0006 (ghcr.io/cordanallm/nucleus/kernels) remains the reserved target for future UKI pushes.

Compliance

  1. Install page against the workflow (tests/test_docs.py::test_install_page_matches_release_workflow): the artifact table in docs/install.md matches the globs that publish-release.yml uploads.
  2. No archive claimed (tests/test_docs.py::test_no_document_claims_an_apt_archive): outside ADR-0004 and this record, no Markdown file or workflow names apt.example.com or reprepro.

References