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
128 changes: 107 additions & 21 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,9 @@ jobs:
- name: Checkout repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ github.event.pull_request.head.ref || github.ref }}
# The triggering commit, not its branch tip: release and
# release-dry-run pair these artifacts with that commit.
ref: ${{ github.event.pull_request.head.sha || github.sha }}
repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }}

- name: Set up just
Expand Down Expand Up @@ -285,36 +287,58 @@ jobs:
retention-days: 7

# Publishes the signed image set as a new, immutable GitHub Release and as
# an ORAS OCI artifact (one layer per file, tags <version> and latest).
# Only runs on pushes/dispatches to main, where the code is already
# reviewed, and is the only job in this workflow that holds write tokens.
# an ORAS OCI artifact (one layer per file, tags <version> and latest), each
# with SLSA build provenance and SBOM attestations. Only runs on
# pushes/dispatches to main, where the code is already reviewed, and is the
# only job in this workflow that holds write tokens. Every publish command
# is scripts/publish-release.sh, which release-dry-run rehearses on each
# pull request.
release:
if: ${{ !failure() && !cancelled() && github.ref == 'refs/heads/main' }}
needs: [build, boot-test]
runs-on: ubuntu-26.04
timeout-minutes: 45
permissions:
contents: write # creates the GitHub Release and uploads its assets
packages: write # pushes the OCI artifact to ghcr.io
packages: write # pushes the OCI artifact and its attestations to ghcr.io
id-token: write # Sigstore signing certificate for the attestations
attestations: write # stores the attestations with the repository
artifact-metadata: write # storage record for the attested ghcr.io artifact
env:
VERSION: ${{ needs.build.outputs.version }}
steps:
- name: Checkout repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- name: Download image artifacts
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
with:
name: image
path: dist/diskless

# A version is published exactly once: creating an existing tag fails
# the job instead of overwriting assets that nodes may already trust.
# Against the committed release keyring, not the build's own copy.
- name: Verify the release set
id: verify
run: bash scripts/publish-release.sh verify dist/diskless "${VERSION}" files/os/sysupdate-keys/import-pubring.gpg

- name: Attest build provenance of the release files
uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
with:
subject-checksums: ${{ steps.verify.outputs.subjects }}

- name: Attest the SBOM of the release files
uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
with:
subject-checksums: ${{ steps.verify.outputs.subjects }}
sbom-path: dist/diskless/bluefin-server_${{ env.VERSION }}.spdx.json

- name: Create GitHub Release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
GH_REPO: ${{ github.repository }}
run: |
set -euo pipefail
V="${{ needs.build.outputs.version }}"
find dist/diskless -maxdepth 1 -type f -print0 | xargs -0 gh release create "v${V}" \
--title "Bluefin Server ${V}" \
--notes "Image ${V} built from ${GITHUB_SHA}."
run: bash scripts/publish-release.sh release dist/diskless "${VERSION}"

# setup-oras v2.0.1's built-in release table stops at ORAS 1.3.3, so pin
# 1.3.4 (matching the Justfile's oras_image) by URL and checksum.
Expand All @@ -325,16 +349,78 @@ jobs:
checksum: f27adb935022d94df8dc77719c322dda592c78a0d57a6f7dcdd8d900b248c454

- name: Push OCI artifact
id: oci
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
set -euo pipefail
V="${{ needs.build.outputs.version }}"
REF="ghcr.io/${GITHUB_REPOSITORY_OWNER,,}/bluefin-server"
echo "${GITHUB_TOKEN}" | oras login ghcr.io -u "${GITHUB_ACTOR}" --password-stdin
cd dist/diskless
mapfile -t files < <(find . -maxdepth 1 -type f -printf '%f\n' | sort)
oras push --artifact-type application/vnd.projectbluefin.server.release.v1 \
--annotation "org.opencontainers.image.version=${V}" \
--annotation "org.opencontainers.image.source=${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}" \
"${REF}:${V},latest" "${files[@]}"
bash scripts/publish-release.sh oci dist/diskless "${VERSION}" "ghcr.io/${GITHUB_REPOSITORY_OWNER,,}/bluefin-server"

# push-to-registry stores the signed attestation next to the artifact
# as an OCI referrer, verifiable with gh attestation or cosign.
- name: Attest build provenance of the OCI artifact
uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
with:
subject-name: ${{ steps.oci.outputs.name }}
subject-digest: ${{ steps.oci.outputs.digest }}
push-to-registry: true

- name: Attest the SBOM of the OCI artifact
uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
with:
subject-name: ${{ steps.oci.outputs.name }}
subject-digest: ${{ steps.oci.outputs.digest }}
sbom-path: dist/diskless/bluefin-server_${{ env.VERSION }}.spdx.json
push-to-registry: true

# Rehearses `release` on every pull request with the same
# scripts/publish-release.sh commands: verifies the release set against the
# keyring the build trusted (a throwaway key on pull requests), renders the
# gh release command without running it, and pushes the OCI artifact to a
# local registry and pulls it back. No secrets, read-only token.
release-dry-run:
if: ${{ github.event_name == 'pull_request' }}
needs: build
runs-on: ubuntu-26.04
timeout-minutes: 45
permissions:
contents: read
services:
registry:
image: docker.io/library/registry:3.1.2@sha256:c87f33837722a100572e95d7dc4bf539fc42cf68202b13c3bc03c0ff54c3a649
ports:
- 5000:5000
env:
VERSION: ${{ needs.build.outputs.version }}
steps:
- name: Checkout repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
# Same commit as `build`: the branch tip may have moved mid-run.
ref: ${{ github.event.pull_request.head.sha || github.sha }}
repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
persist-credentials: false

- name: Download image artifacts
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
with:
name: image
path: dist/diskless

- name: Verify the release set
run: bash scripts/publish-release.sh verify dist/diskless "${VERSION}" dist/diskless/sysupdate-keys/import-pubring.pgp

- name: Render the GitHub Release
run: bash scripts/publish-release.sh release dist/diskless "${VERSION}" --dry-run

# setup-oras v2.0.1's built-in release table stops at ORAS 1.3.3, so pin
# 1.3.4 (matching the Justfile's oras_image) by URL and checksum.
- name: Set up oras
uses: oras-project/setup-oras@1d808f7d7f6995cc68b7bf507bfe5c5446e1dc9d # v2.0.1
with:
url: https://github.com/oras-project/oras/releases/download/v1.3.4/oras_1.3.4_linux_amd64.tar.gz
checksum: f27adb935022d94df8dc77719c322dda592c78a0d57a6f7dcdd8d900b248c454

- name: Push the OCI artifact to a local registry and pull it back
run: bash scripts/publish-release.sh oci dist/diskless "${VERSION}" localhost:5000/bluefin-server --plain-http --pull-back
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,10 @@ Bluefin Server is an image-based Linux server OS composed from freedesktop-sdk (
- a netboot ESP image with signed systemd-boot and Secure Boot key enrollment payloads
- an offline USB installer `bluefin-server-installer_<ver>.raw` (usr + usr-verity + ESP with systemd-boot, the installer UKI, the disk UKI and `repart.d`) that boots into `systemd-sysinstall`
- optional opt-in `systemd-sysext` images: `oci/k0s-sysext.bst` (controller, or worker when `/etc/k0s/token` exists), `oci/kubestellar-sysext.bst` (Argo CD, KubeStellar, kiosk; needs k0s), `oci/kubeadm-sysext.bst` (kubeadm worker: kubelet, containerd) and `oci/zfs-sysext.bst`
- an SPDX 2.3 SBOM `bluefin-server_<ver>.spdx.json` (`oci/bluefin-server-sbom.bst`)
- a `SHA256SUMS` over the whole set, signed in-element (`SHA256SUMS.gpg`); nodes verify it against `/etc/systemd/import-pubring.pgp`

A release publishes `dist/diskless/` as-is: a GitHub Release `v<ver>` and an ORAS OCI artifact `ghcr.io/<owner>/bluefin-server:<ver>,latest`.
A release publishes `dist/diskless/` as-is: a GitHub Release `v<ver>` and an ORAS OCI artifact `ghcr.io/<owner>/bluefin-server:<ver>,latest`, both with provenance and SBOM attestations; pull requests rehearse it in `release-dry-run`.

## What agents should know first

Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@ See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the contributor checklist, Conventi
- **Signed boot chain**: Secure Boot keys enroll from the ESP on first boot (`secure-boot-enroll if-safe` in VMs, or manually via systemd-boot menu in firmware Setup Mode on bare metal); local builds use throwaway keys from `just gen-dev-keys`.
- **Signed manifests**: the build signs one combined `SHA256SUMS` over the whole image set (OS images, UKIs, sysexts) inside `oci/bluefin-server-image.bst`; a release publishes `dist/diskless/` as-is to GitHub Releases and as an OCI artifact.
- **Sysupdate verification**: installed nodes verify updates against the signed manifest (`Verify=yes`), and the diskless pull checks the same signature in the initrd; see [`docs/skills/systemd-sysupdate-verification.md`](docs/skills/systemd-sysupdate-verification.md) for details.
- **Provenance and SBOM**: releases carry SLSA provenance and SPDX SBOM attestations; see [`docs/skills/systemd-sysupdate-verification.md`](docs/skills/systemd-sysupdate-verification.md) for verification.
- **Vulnerability disclosure**: See [`SECURITY.md`](SECURITY.md) for policy details and how to report security issues.

## License
Expand Down
21 changes: 17 additions & 4 deletions docs/skills/ci-tooling.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,8 +72,13 @@ may hold a write token. In `build.yml`, write tokens are granted to exactly
one job:

- `release` — creates the GitHub Release and pushes the OCI artifact; gated to
`refs/heads/main`. It holds `contents: write` (release) and
`packages: write` (ghcr.io push).
`refs/heads/main`. It holds `contents: write` (release),
`packages: write` (ghcr.io push and attestation referrers), and
`id-token: write`, `attestations: write` and `artifact-metadata: write`
for the provenance and SBOM attestations.

Its pull-request rehearsal, `release-dry-run`, keeps the read-only default
and uses no secrets.

Junction ref tracking must never run on `pull_request`. It used to, as a
`track-refs` job gated on `startsWith(github.head_ref, 'renovate/')`, and a
Expand Down Expand Up @@ -120,7 +125,8 @@ sudo_cmd := if `podman info >/dev/null 2>&1 && echo 1 || echo 0` == "1" { "" } e
| `changes` | `build.yml` | `pull_request`, `push/main`, `workflow_dispatch` | Decides whether `build` and `boot-test` run: always outside pull requests; on a pull request only if `.github/scripts/image-build-needed.py`, checked out from the PR's base revision, finds a changed path that can reach the image set or the boot test (see [Build time and caches](#build-time-and-caches)). `contents: read` + `pull-requests: read`. |
| `build` | `build.yml` | `pull_request`, `push/main`, `workflow_dispatch` | Resolves the element graph, sets `image-version`, and runs the full BuildStream compile of the image set (OS DDI, signed UKIs, netboot ESP, k0s/KubeStellar/OpenZFS sysext assets), which also writes and signs the combined `SHA256SUMS` inside `oci/bluefin-server-image.bst`. On `main` it installs the `BOOT_KEYS_TARBALL` and `SYSUPDATE_SIGNING_KEY` secrets; both are required there. Off `main` it also exports two higher-versioned sets (`1.<run>.1`, `1.<run>.2`) for the update test. Read-only token. |
| `boot-test` | `build.yml` | `pull_request`, `push/main`, `workflow_dispatch` | Runs the Secure Boot QEMU checks on the exported sets (see Core Process step 4). Read-only token. |
| `release` | `build.yml` | `push/main`, `workflow_dispatch` | Publishes `dist/diskless/` as-is: an immutable GitHub Release tagged `v<image-version>` plus an ORAS OCI artifact at `ghcr.io/<owner>/bluefin-server:<ver>,latest` (one layer per file, artifact type `application/vnd.projectbluefin.server.release.v1`) (`if: ${{ !failure() && !cancelled() && github.ref == 'refs/heads/main' }}`). `contents: write` + `packages: write`. |
| `release` | `build.yml` | `push/main`, `workflow_dispatch` | Publishes `dist/diskless/` as-is through `scripts/publish-release.sh`: an immutable GitHub Release tagged `v<image-version>` plus an ORAS OCI artifact at `ghcr.io/<owner>/bluefin-server:<ver>,latest` (one layer per file, artifact type `application/vnd.projectbluefin.server.release.v1`), with provenance and SBOM attestations for both (`if: ${{ !failure() && !cancelled() && github.ref == 'refs/heads/main' }}`). Write permissions listed above. |
| `release-dry-run` | `build.yml` | `pull_request` | Runs the same `scripts/publish-release.sh` commands against the PR's image set: verify, render `gh release create`, and a real `oras push` to a `registry` service container (pinned by digest) that it pulls back. Read-only token, no secrets. |
| `docs` | `docs-checks.yml` | `pull_request`, `push/main` | Runs markdown and skill metadata checks via `docs-checks.py`. Read-only token. |
| `unit` | `unit-tests.yml` | `pull_request`, `push/main` | Runs pytest and BATS unit test suites. Read-only token. |
| `check`, `propose` | `track-binaries.yml` | `schedule` (08:30 UTC), `workflow_dispatch` | `check` finds the newest patch release in each pinned series of the upstream binaries pinned by version + sha256 (Kubernetes, cri-tools, containerd, runc, CNI plugins, k0s, ORAS) with `.github/scripts/track-binaries.py`; `propose` moves each version together with its sha256 pins, verified against upstream's checksum files and the downloaded assets, and opens or updates one PR per component on `auto/track-binaries/<component>`. Minor bumps stay manual (`kubeadm-sysext.md`, `k0s-sysext.md`). Read-only `GITHUB_TOKEN`; writes use the mergeraptor app token narrowed to `contents` + `pull-requests` (+ `workflows` for ORAS, pinned in `build.yml`). Never on `pull_request`. |
Expand Down Expand Up @@ -178,7 +184,11 @@ uploaded to a GitHub Release tagged `v<image-version>` (`YY.MM.<run>` on main).
merges), GitHub Actions publishes `dist/diskless/` as-is: an immutable
GitHub Release `v<image-version>` and an ORAS OCI artifact
`ghcr.io/<owner>/bluefin-server:<ver>,latest`. Nodes verify updates
against the `SHA256SUMS` / `SHA256SUMS.gpg` already in that set.
against the `SHA256SUMS` / `SHA256SUMS.gpg` already in that set. Every
pull request rehearses this path in `release-dry-run`, so the publish
code is exercised before it first runs on main. Attestations, the SBOM
and the verify commands are in
[`systemd-sysupdate-verification.md`](systemd-sysupdate-verification.md).

## Build time and caches

Expand Down Expand Up @@ -261,6 +271,9 @@ per-set cost is estimated at under 10 min.
- [ ] Release signing happens in `oci/bluefin-server-image.bst`; there is no
separate CI signing step, and the release job publishes `dist/diskless/`
as-is (GitHub Release + OCI artifact).
- [ ] Publish logic lives in `scripts/publish-release.sh`, not inline in the
workflow; `tests/unit/test_release_workflow.py` keeps `release` and
`release-dry-run` on the same commands and the same `setup-oras` pin.
- [ ] The signing secret names (`BOOT_KEYS_TARBALL`, `SYSUPDATE_SIGNING_KEY`)
match the ones documented in
`docs/skills/systemd-sysupdate-verification.md`.
Expand Down
Loading