Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 53 additions & 17 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,14 @@ name: Release
# per-architecture workflow artifacts for review/testing.
# - tag push v*.*.*: publishes a stable release at that tag.
# - workflow_dispatch: manual run for ad-hoc rebuilds.
#
# Every published .deb gets a GitHub build-provenance attestation, recorded in
# the public Sigstore transparency log. It ties the package's digest to this
# repository, workflow and commit, so anyone can check that a SmoothKernel
# package (from a release or from the Smooth* apt repository, which publishes
# them unmodified) was built here:
#
# gh attestation verify <package>.deb --repo RakuenSoftware/smoothkernel
on:
push:
branches: [main]
Expand All @@ -22,6 +30,8 @@ on:

permissions:
contents: write
id-token: write # build-provenance attestations (Sigstore)
attestations: write

env:
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
Expand All @@ -35,6 +45,7 @@ jobs:
prerelease: ${{ steps.meta.outputs.prerelease }}
kernel_version: ${{ steps.meta.outputs.kernel_version }}
zfs_version: ${{ steps.meta.outputs.zfs_version }}
build_number: ${{ steps.meta.outputs.build_number }}
steps:
- uses: actions/checkout@v4
with:
Expand All @@ -47,6 +58,9 @@ jobs:
KERNEL_VERSION="$(awk -F= '/^KERNEL_VERSION=/ {gsub(/[ \t]/,""); print $2; exit}' examples/smooth.env)"
ZFS_VERSION="$(awk -F= '/^ZFS_VERSION=/ {gsub(/[ \t]/,""); print $2; exit}' examples/smooth.env)"
SHORT_SHA="$(git rev-parse --short HEAD)"
# Package versions and the kernel release carry it (see
# recipes/build-number.sh); computed once so every job agrees.
BUILD_NUMBER="$(recipes/build-number.sh)"

if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
TAG="${GITHUB_REF#refs/tags/}"
Expand All @@ -63,6 +77,8 @@ jobs:
echo "prerelease=${PRERELEASE}" >> "$GITHUB_OUTPUT"
echo "kernel_version=${KERNEL_VERSION}" >> "$GITHUB_OUTPUT"
echo "zfs_version=${ZFS_VERSION}" >> "$GITHUB_OUTPUT"
echo "build_number=${BUILD_NUMBER}" >> "$GITHUB_OUTPUT"
echo "SmoothKernel ${KERNEL_VERSION} build ${BUILD_NUMBER}: kernel release ${KERNEL_VERSION}-${BUILD_NUMBER}-smoothkernel"

build:
needs: meta
Expand All @@ -76,6 +92,8 @@ jobs:
runner: ubuntu-24.04-arm
runs-on: ${{ matrix.runner }}
timeout-minutes: 180
env:
BUILD_NUMBER: ${{ needs.meta.outputs.build_number }}
steps:
- uses: actions/checkout@v4
with:
Expand Down Expand Up @@ -111,8 +129,9 @@ jobs:
# workspace so it is never picked up by artifact upload, and is removed
# again by the cleanup step below (which runs even if the build fails).
#
# Fork PRs do not receive secrets. Those builds still run, but produce
# unsigned developer artifacts marked as not promotable.
# Without the secrets (fork PRs never get them) the build still runs and
# produces an unsigned kernel, marked as such, which runs only with
# Secure Boot off.
- name: Materialize signing material
id: signing
env:
Expand Down Expand Up @@ -151,7 +170,7 @@ jobs:
echo "Signing material present: modules + kernel image."
else
echo "signed=0" >> "$GITHUB_OUTPUT"
echo "::warning::Signing secrets absent or incomplete (modules=$have_modsig, secureboot=$have_sb). Artifacts will be UNSIGNED developer builds and are not promotable."
echo "::warning::Signing secrets absent or incomplete (modules=$have_modsig, secureboot=$have_sb). The kernel is unsigned and runs only with Secure Boot off."
fi

- name: Install signing tools
Expand Down Expand Up @@ -217,17 +236,19 @@ jobs:
- name: Mark unsigned build
if: steps.signing.outputs.signed != '1'
run: |
echo "::warning::This build is UNSIGNED and not promotable per docs/signing.md."
echo "::warning::This build is UNSIGNED: it runs only with Secure Boot off (docs/signing.md)."
mkdir -p "out/${{ matrix.deb_arch }}"
cat > "out/${{ matrix.deb_arch }}/UNSIGNED-NOT-PROMOTABLE.txt" <<'EOF'
These packages were built without release signing material.
cat > "out/${{ matrix.deb_arch }}/UNSIGNED.txt" <<'EOF'
These packages were built without signing material.

Packaged modules carry an ephemeral "Build time autogenerated kernel
key" and the kernel image has no EFI signature, so it will be refused
by shim on a Secure Boot machine ("bad shim signature").
key" and the kernel image has no EFI signature, so shim refuses it on
a Secure Boot machine ("bad shim signature"). Run it with Secure Boot
off. See docs/signing.md.

Valid for development and functional testing. NOT promotable to the
apt repo. See docs/signing.md.
Where the packages came from is shown by their build-provenance
attestations, not by signing:
gh attestation verify <package>.deb --repo RakuenSoftware/smoothkernel
EOF

- name: Stage release artifacts
Expand All @@ -237,14 +258,22 @@ jobs:
cp "out/${{ matrix.deb_arch }}"/*.deb "dist/${{ matrix.deb_arch }}/"
# The unsigned-build marker is not a .deb, so it has to be copied
# explicitly or it never leaves out/ — the artifact would then look
# identical to a promotable one, which is the whole point of it.
marker="out/${{ matrix.deb_arch }}/UNSIGNED-NOT-PROMOTABLE.txt"
# identical to a signed one, which is the whole point of it.
marker="out/${{ matrix.deb_arch }}/UNSIGNED.txt"
if [ -f "$marker" ]; then
cp "$marker" "dist/${{ matrix.deb_arch }}/"
echo "staged unsigned-build marker"
fi
(cd "dist/${{ matrix.deb_arch }}" && sha256sum *.deb > "SHA256SUMS.${{ matrix.deb_arch }}")
ls -lh "dist/${{ matrix.deb_arch }}/"
# Publish each package's identity as a run annotation: annotations
# are readable without GitHub auth, unlike logs and artifacts, so
# anyone can check names, versions and dependencies of a build.
summary=""
for deb in "dist/${{ matrix.deb_arch }}"/*.deb; do
summary+="$(dpkg-deb -W --showformat='${Package} ${Version} Depends: ${Depends} Provides: ${Provides}' "$deb")%0A"
done
echo "::notice title=packages ${{ matrix.deb_arch }}::${summary}"

- name: Upload package artifact
uses: actions/upload-artifact@v4
Expand Down Expand Up @@ -292,13 +321,13 @@ jobs:
done

# Carry the unsigned-build marker into the published release. Without
# this the release assets are indistinguishable from a promotable
# build, which is exactly what the marker exists to prevent.
# this the release assets are indistinguishable from a signed build,
# which is exactly what the marker exists to prevent.
for arch in amd64 arm64; do
m="release-input/packages-${arch}/UNSIGNED-NOT-PROMOTABLE.txt"
m="release-input/packages-${arch}/UNSIGNED.txt"
if [ -f "$m" ]; then
cp "$m" dist/
echo "::warning::This release was built WITHOUT signing material and is not promotable."
echo "::warning::This release was built WITHOUT signing material; it runs only with Secure Boot off."
break
fi
done
Expand All @@ -312,6 +341,8 @@ jobs:
printf ' "tag": "%s",\n' "${{ needs.meta.outputs.tag }}"
printf ' "kernel_version": "%s",\n' "${{ needs.meta.outputs.kernel_version }}"
printf ' "zfs_version": "%s",\n' "${{ needs.meta.outputs.zfs_version }}"
printf ' "build_number": %s,\n' "${{ needs.meta.outputs.build_number }}"
printf ' "kernel_release": "%s",\n' "${{ needs.meta.outputs.kernel_version }}-${{ needs.meta.outputs.build_number }}-smoothkernel"
printf ' "commit": "%s",\n' "${GITHUB_SHA}"
printf ' "architectures": ["amd64", "arm64"],\n'
printf ' "artifacts": [\n'
Expand All @@ -331,6 +362,11 @@ jobs:

ls -lh dist/

- name: Attest build provenance
uses: actions/attest-build-provenance@v2
with:
subject-path: dist/*.deb

- name: Create GitHub release
uses: softprops/action-gh-release@v2
with:
Expand All @@ -342,5 +378,5 @@ jobs:
dist/*.deb
dist/SHA256SUMS
dist/manifest.json
dist/UNSIGNED-NOT-PROMOTABLE.txt
dist/UNSIGNED.txt
generate_release_notes: true
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ smoothkernel/
|-- recipes/
| |-- build-kernel.sh Kernel build recipe
| |-- build-zfs.sh OpenZFS package recipe
| `-- stamp-version.sh Version helper
| `-- build-number.sh Build number for package versions
|-- templates/
| |-- dkms.conf.in DKMS package template
| |-- debian-postinst.in DKMS register/build/install hook
Expand Down
27 changes: 9 additions & 18 deletions docs/APT_REPO.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,13 @@

Design for the Smooth* apt repository: suite layout, component choices, pinning, promotion, and the minimum repository mechanics the rest of this doc set assumes.

The sibling `apt-repo` repo may carry the implementation details, but the cross-repo contract is:
The repository is [`smoothapt`](https://github.com/RakuenSoftware/smoothapt), which carries the implementation details. The cross-repo contract is:

- `pool/` and `dists/` are committed artifacts, not generated on the web host
- `scripts/add-package.sh` adds packages, refreshes indices, and updates `Release` metadata
- `Origin: RakuenSoftware` is set in each signed `Release` file
- CI signs `Release` / `InRelease`, publishes `public-key.asc`, and deploys the static tree
- It runs on the VPS and ingests every Smooth* project from that project's GitHub releases: SmoothKernel into `common`, each product into its own suite. Builds happen only in each project's GitHub pipeline; `smoothapt` never builds, re-signs or re-versions a package.
- Before ingesting a package it verifies the package's build-provenance attestation against the project's repository, so every package in the repository is traceable to a public pipeline run (SmoothKernel: [CI_RELEASES.md](CI_RELEASES.md#provenance)).
- The archive (`pool/`, `dists/`) lives on the server, not in git.
- `Origin: RakuenSoftware` is set in each signed `Release` file, and `public-key.asc` is published alongside.
- The `smoothrouter` suite, and its packages, are served only to clients with a per-user credential that can be revoked.

## Suite layout

Expand Down Expand Up @@ -92,29 +93,19 @@ This keeps our version strictly greater than Debian's (`25.2.3` alone or `25.2.3

## Promotion

v1 (now): one suite per flavor, `main` component, direct publish. Matches the existing `apt-repo` shape.
v1 (now): one suite per flavor, `main` component, direct publish.

v2 (when rebase pain justifies it): introduce a `testing` suite tree mirrored from `common`/`smoothnas`/etc. CI builds land in `testing-<suite>`; soak for N days; a promotion script copies approved packages across. Keeps the producer-side simple while letting us de-risk kernel bumps.

The promotion machinery is non-trivial (needs to preserve signatures or re-sign). Defer until we're shipping to more than test boxes.

## Signing and key custody

Already addressed in `apt-repo/README.md` (Section: One-time setup). Single signing key, stored as GitHub repo secret `APT_SIGNING_KEY`. Key-id as `APT_SIGNING_KEY_ID`. Public half served as `public-key.asc` from the repo root; consumers dearmor into `/etc/apt/keyrings/smooth-archive-keyring.gpg`.

Not changing this — the existing shape is fine.
Single repository signing key; custody is documented in `smoothapt`. Public half served as `public-key.asc`; consumers dearmor into `/etc/apt/keyrings/smooth-archive-keyring.gpg`.

## Hosting

GitHub Pages (current). Mirrorable to any static HTTP server — `dists/` is committed, so a `git clone` into `/var/www/apt-repo` is a complete mirror. No server-side build needed.

Production will eventually want:

- A stable custom domain (`apt.rakuensoftware.com`)
- CDN in front (Cloudflare works with GitHub Pages)
- HTTPS enforced (GitHub Pages provides this)

Out of scope until we ship to real users.
The Rakuen VPS, as a static tree behind nginx with HTTPS. `smoothapt` documents the setup.

## Out-of-tree modules and DKMS

Expand Down
73 changes: 60 additions & 13 deletions docs/CI_RELEASES.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,32 @@ v<kernel-version>-<short-sha>

Tag pushes produce stable GitHub releases at the pushed tag.

## Versions

Every build has a build number: the commit count of the built commit
(`recipes/build-number.sh`). It names the kernel and versions every package,
so each build of `main` is distinct and newer than the last:

| Package | Example (kernel 7.2.10, build 68) |
|---|---|
| `linux-image-<release>` | `linux-image-7.2.10-68-smoothkernel_7.2.10-68_amd64.deb` |
| `linux-headers-<release>` | `linux-headers-7.2.10-68-smoothkernel_7.2.10-68_amd64.deb` |
| `linux-libc-dev` | `linux-libc-dev_7.2.10-68_amd64.deb` |
| `linux-image-smoothkernel` (metapackage) | `linux-image-smoothkernel_7.2.10-68_amd64.deb` |
| `linux-headers-smoothkernel` (metapackage) | `linux-headers-smoothkernel_7.2.10-68_amd64.deb` |
| OpenZFS | `zfs_2.4.4-68_amd64.deb`, `zfs-dkms_2.4.4-68_amd64.deb`, ... |

The kernel release (`uname -r`) is `7.2.10-68-smoothkernel`, so a new build
installs alongside the running kernel rather than replacing its modules, and
the previous kernel stays bootable. Systems install the two metapackages, each
of which depends on exactly its build's package, so `apt upgrade` moves them to
every new build. Old kernels are removed by `apt autoremove`, which keeps the
running and newest ones. The versioned headers package also `Provides:
linux-headers`, for DKMS packages that depend on the generic name.

The DKMS module version of OpenZFS stays the upstream version (`2.4.4`); only
the package revision carries the build number.

## Build Steps

The workflow:
Expand All @@ -34,7 +60,25 @@ The workflow:
7. Merges amd64 and arm64 packages into `dist/`, skipping duplicate `_all.deb` assets.
8. Writes `dist/SHA256SUMS`.
9. Writes `dist/manifest.json` with artifact architectures and sha256 values.
10. Publishes a GitHub Release with `.deb`, checksum, and manifest assets.
10. Attests the build provenance of every `.deb` (see below).
11. Publishes a GitHub Release with `.deb`, checksum, and manifest assets.

## Provenance

Every published `.deb` carries a GitHub build-provenance attestation: a
statement signed through Sigstore and recorded in its public transparency log
that ties the package's SHA-256 to this repository, the workflow, and the
commit it was built from. Anyone can check a package, whether it came from a
GitHub Release or from the Smooth* apt repository:

```sh
gh attestation verify linux-image-7.2.10-68-smoothkernel_7.2.10-68_amd64.deb \
--repo RakuenSoftware/smoothkernel
```

The apt repository publishes these packages byte for byte as released, so the
checksums in its indices are the attested ones. Nothing downstream rebuilds,
re-signs or re-versions a SmoothKernel package.

## Manifest

Expand All @@ -44,13 +88,13 @@ release contents. It records:
- Release tag.
- Kernel version.
- ZFS version.
- Build number and kernel release (`uname -r`).
- Git commit.
- Supported architectures.
- Artifact names, Debian architecture suffixes, and sha256 values.

Consumers should still verify package signatures and apt repository metadata
when installing from the Smooth* apt repo. The GitHub Release manifest is an
artifact inventory, not a substitute for apt trust.
The manifest is an artifact inventory, not a statement of provenance; that is
what the attestations are.

## GitHub Release vs Apt Promotion

Expand All @@ -59,24 +103,27 @@ itself mean "these artifacts are promoted to users."

Promotion to the Smooth* apt repository requires:

- Release-grade provenance checks.
- Signing requirements from [signing.md](signing.md).
- A valid build-provenance attestation for every package, from this
repository's release workflow. The apt repository checks it before
ingesting a package.
- Representative flavor smoke tests.
- Apt repository indexing and signed `Release` / `InRelease` metadata.

Signing is not required: an unsigned release is promoted like a signed one and
runs only with Secure Boot off (see [signing.md](signing.md)).

The apt repository is the user-facing distribution mechanism. GitHub Releases
are useful for builders, downstream automation, and pre-promotion testing.

## Signing Boundary

This repository must not store private module-signing keys. The production
contract in [signing.md](signing.md) requires release-built modules to be signed
by controlled CI signing material and DKMS modules to be signed on-host.
This repository must not store private module-signing keys. When signing
material is provisioned, [signing.md](signing.md) has release-built modules
signed by controlled CI signing material and DKMS modules signed on-host.

If the GitHub workflow is used for promotable artifacts, it must be wired to the
approved signing mechanism before promotion. Local developer builds and unsigned
CI builds are acceptable for bring-up and smoke testing, but they are not final
Secure-Boot release artifacts.
Without it, CI builds unsigned kernels, marked with `UNSIGNED.txt`, which run
only with Secure Boot off. Local developer builds are for bring-up and smoke
testing only; only CI-built packages are promoted.

## Failure Handling

Expand Down
2 changes: 1 addition & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ Product-level contract described here:

- The Smooth* apt repository consumes and promotes release artifacts.
- Flavor repositories own their daemons, UIs, meta packages, and smoke tests.
- Signing-capable CI owns release-key custody and promotable signed artifacts.
- CI builds and attests every released package; signing, when its secrets are provisioned, also happens there.
- Installers own first-boot setup and flavor-specific source enablement.

If a doc makes a production claim that is not implemented yet, prefer language
Expand Down
Loading
Loading