ci: publish Cloud Hypervisor test artifacts as release assets

.github/workflows/release.yml

@@ -21,7 +21,7 @@ permissions:
   contents: write   # Required for creating releases, pushing version commits and tags
   packages: write   # Required for pushing to GHCR
   id-token: write   # Required for cosign keyless signing
-  attestations: write # Required for Firecracker test artifact provenance
+  attestations: write # Required for Firecracker/Cloud Hypervisor test artifact provenance
 
 jobs:
   bump-version:
@@ -721,7 +721,7 @@ jobs:
   release:
     name: Create Release
     runs-on: ubuntu-latest
-    needs: [bump-version, build-squid, build-agent, build-api-proxy, build-cli-proxy, build-agent-act, build-build-tools, build-enclaves, build-gh-aw-node, build-firecracker-test-artifacts]
+    needs: [bump-version, build-squid, build-agent, build-api-proxy, build-cli-proxy, build-agent-act, build-build-tools, build-enclaves, build-gh-aw-node, build-firecracker-test-artifacts, build-cloud-hypervisor-test-artifacts]
     steps:
       - name: Checkout code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4
@@ -829,6 +829,23 @@ jobs:
           cp firecracker-release-assets/sbom.spdx.json \
             release/firecracker-test-x86_64.sbom.spdx.json
 
+      - name: Download Cloud Hypervisor preview test artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: release-cloud-hypervisor-test-x86_64
+          path: cloud-hypervisor-release-assets
+
+      - name: Stage Cloud Hypervisor preview test assets
+        run: |
+          cp cloud-hypervisor-release-assets/awf-cloud-hypervisor-test-x86_64.tar.gz \
+            release/cloud-hypervisor-test-x86_64.tar.gz
+          cp cloud-hypervisor-release-assets/SHA256SUMS \
+            release/cloud-hypervisor-test-x86_64.SHA256SUMS
+          cp cloud-hypervisor-release-assets/manifest.json \
+            release/cloud-hypervisor-test-x86_64.manifest.json
+          cp cloud-hypervisor-release-assets/sbom.spdx.json \
+            release/cloud-hypervisor-test-x86_64.sbom.spdx.json
+
       - name: Generate containers list
         run: |
           mkdir -p release
@@ -988,6 +1005,10 @@ jobs:
             release/firecracker-test-x86_64.SHA256SUMS
             release/firecracker-test-x86_64.manifest.json
             release/firecracker-test-x86_64.sbom.spdx.json
+            release/cloud-hypervisor-test-x86_64.tar.gz
+            release/cloud-hypervisor-test-x86_64.SHA256SUMS
+            release/cloud-hypervisor-test-x86_64.manifest.json
+            release/cloud-hypervisor-test-x86_64.sbom.spdx.json
             release/containers.txt
             release/awf-config.schema.json
             release/awf-config.v1.schema.json
@@ -1048,3 +1069,47 @@ jobs:
           path: release/firecracker-test-x86_64/
           if-no-files-found: error
           retention-days: 7
+
+  build-cloud-hypervisor-test-artifacts:
+    name: Build Cloud Hypervisor Preview Test Artifacts
+    runs-on: ubuntu-24.04
+    needs: bump-version
+    timeout-minutes: 45
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4
+        with:
+          ref: ${{ needs.bump-version.outputs.version }}
+
+      - name: Set up Go
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version: '1.25.0'
+          cache-dependency-path: guest/firecracker-supervisor/go.mod
+
+      - name: Install guest build prerequisites
+        run: |
+          sudo apt-get update
+          sudo apt-get install --yes --no-install-recommends \
+            bc binutils bison build-essential ca-certificates cpio e2fsprogs \
+            file flex libelf-dev libssl-dev rsync xz-utils
+
+      - name: Build and verify pinned test artifacts
+        run: |
+          VERSION="${{ needs.bump-version.outputs.version }}" \
+            ./guest/cloud-hypervisor/build-test-artifacts.sh
+          ./guest/cloud-hypervisor/verify-test-artifacts.sh \
+            release/cloud-hypervisor-test-x86_64
+
+      - name: Attest guest artifact provenance
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+        with:
+          subject-path: release/cloud-hypervisor-test-x86_64/awf-cloud-hypervisor-test-x86_64.tar.gz
+
+      - name: Upload Cloud Hypervisor test artifacts
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        with:
+          name: release-cloud-hypervisor-test-x86_64
+          path: release/cloud-hypervisor-test-x86_64/
+          if-no-files-found: error
+          retention-days: 7

docs/awf-config-spec.md

@@ -112,13 +112,13 @@ for the guest artifact build/verification pipeline. See
 the full architecture and security-boundary writeup.
 
 Release test artifacts (`cloud-hypervisor-test-x86_64`) are x86_64
-test/preview artifacts built and verified by
+test/preview artifacts built and verified by both the release workflow and
 [`test-cloud-hypervisor.yml`](../.github/workflows/test-cloud-hypervisor.yml),
 which also runs the live-KVM parity/security smoke suite
 (`scripts/ci/cloud-hypervisor-live-smoke.sh`) on GitHub-hosted Ubuntu x86_64
 runners when triggered by manual dispatch or the `cloud-hypervisor-kvm` pull
-request label. They are published as workflow artifacts, but are not
-production defaults and are never auto-downloaded. See
+request label. They are published as explicitly named release/workflow
+assets, but are not production defaults and are never auto-downloaded. See
 [docs/cloud-hypervisor-foundation.md](./cloud-hypervisor-foundation.md#part-14--ci-workflow)
 for the complete CI workflow specification and troubleshooting reference.
 
@@ -223,7 +223,7 @@ AWF settings MAY be supplied via config files, including stdin (`--config -`).
 - `container.dockerHostPathPrefix` → `--docker-host-path-prefix`
 - `container.runnerToolCachePath` → *(config-only; checked first for optional read-only runner tool cache mount, before `RUNNER_TOOL_CACHE` and `/home/runner/work/_tool` auto-detection)*
 - `container.mounts[]` → `-v, --mount` *(repeatable; each array entry maps to one Docker volume mount in `/host_path:/container_path[:ro|rw]` format (both paths must be absolute; host path must exist); in chroot mode, container paths are automatically prefixed with `/host`)*
-- `container.containerRuntime` → `--container-runtime` *(user-facing runtime name: `"gvisor"` for OCI runtime in compose, `"sbx"` for Docker sbx microVM, or `"firecracker"` for the explicit Firecracker v1.16.1 workload preview. For gvisor: translates to `"runsc"`, injects `extra_hosts` for DNS workaround. For sbx and Firecracker: infrastructure stays in Compose while the primary agent runs in a microVM.)*
+- `container.containerRuntime` → `--container-runtime` *(user-facing runtime name: `"gvisor"` for OCI runtime in compose, `"sbx"` for Docker sbx microVM, `"firecracker"` for the explicit Firecracker v1.16.1 workload preview, or `"cloud-hypervisor"` for the explicit Cloud Hypervisor v53.0 workload preview (GitHub-hosted Ubuntu x86_64 KVM runners only; see §4.1). For gvisor: translates to `"runsc"`, injects `extra_hosts` for DNS workaround. For sbx, Firecracker, and Cloud Hypervisor: infrastructure stays in Compose while the primary agent runs in a microVM.)*
 - `firecracker.previewEnabled` → `--firecracker-preview`
 - `firecracker.firecrackerBinary` → `--firecracker-binary`
 - `firecracker.jailerBinary` → `--firecracker-jailer-binary`

guest/cloud-hypervisor/build-test-artifacts.sh

@@ -21,9 +21,12 @@ umask 077
 # itself as VMM-neutral (length-prefixed JSON framing over vsock/UDS), so no
 # Cloud Hypervisor-specific supervisor is needed.
 #
-# NOTE: this produces artifacts for the Cloud Hypervisor *foundation* only.
-# There is no lifecycle backend yet (see src/cloud-hypervisor/), so these
-# artifacts are not wired into any runnable AWF workload in this release.
+# NOTE: these artifacts back the real Cloud Hypervisor lifecycle backend in
+# src/cloud-hypervisor/ (preview, gated behind --cloud-hypervisor-preview
+# plus --container-runtime cloud-hypervisor on GitHub-hosted Ubuntu x86_64
+# KVM runners only). They are published as a versioned GitHub Release asset
+# (cloud-hypervisor-test-x86_64.tar.gz, see .github/workflows/release.yml)
+# for external tooling to pin against, not just as an ephemeral CI artifact.
 
 CLOUD_HYPERVISOR_VERSION=53.0
 CLOUD_HYPERVISOR_BINARY_SHA256=448af3d4e59b22c2987f7df94c213ad40fb53a10d437e42b5ee6c4fce7c29ecc
@@ -169,7 +172,7 @@ make -C "$busybox_dir" -j"$JOBS"
 # guest/firecracker-supervisor/protocol.go) and is shared as-is between the
 # Firecracker and Cloud Hypervisor guest pipelines.
 supervisor="$OUTPUT/awf-supervisor"
-VERSION="v${CLOUD_HYPERVISOR_VERSION}" \
+VERSION="${VERSION:-v${CLOUD_HYPERVISOR_VERSION}}" \
   OUTPUT="$supervisor" \
   "$ROOT/guest/firecracker-supervisor/build.sh"
 
@@ -236,7 +239,7 @@ E2FSPROGS_FAKE_TIME="$SOURCE_DATE_EPOCH" e2fsck -f -y "$rootfs" >/dev/null
 cat >"$OUTPUT/manifest.json" <<EOF
 {
   "schemaVersion": 1,
-  "purpose": "AWF Cloud Hypervisor foundation test artifacts; not production defaults; no lifecycle backend yet",
+  "purpose": "AWF Cloud Hypervisor preview test artifacts; not production defaults",
   "architecture": "x86_64",
   "sourceDateEpoch": ${SOURCE_DATE_EPOCH},
   "cloudHypervisor": {

guest/cloud-hypervisor/verify-test-artifacts.sh

@@ -27,6 +27,6 @@ file "$ARTIFACT_DIR/vmlinux.bin" | grep -E 'Linux kernel|boot executable'
 e2fsck -f -n "$ARTIFACT_DIR/rootfs.ext4"
 debugfs -R 'stat /sbin/awf-supervisor' "$ARTIFACT_DIR/rootfs.ext4" 2>&1 \
   | grep -F 'Type: regular'
-grep -F '"purpose": "AWF Cloud Hypervisor foundation test artifacts; not production defaults; no lifecycle backend yet"' \
+grep -F '"purpose": "AWF Cloud Hypervisor preview test artifacts; not production defaults"' \
   "$ARTIFACT_DIR/manifest.json"
 grep -F '"spdxVersion": "SPDX-2.3"' "$ARTIFACT_DIR/sbom.spdx.json"

src/config-file.ts

@@ -136,9 +136,10 @@ export interface AwfFileConfig {
     sha256?: FirecrackerArtifactDigests;
   };
   /**
-   * Cloud Hypervisor microVM foundation (config/artifacts only).
-   * There is no lifecycle backend yet: this cannot be selected via
-   * `container.containerRuntime`.
+   * Cloud Hypervisor v53.0 preview microVM runtime.
+   * Selectable via `container.containerRuntime: "cloud-hypervisor"`, gated
+   * behind `previewEnabled`/`--cloud-hypervisor-preview`. Supported only on
+   * GitHub-hosted Ubuntu x86_64 KVM runners.
    */
   cloudHypervisor?: {
     previewEnabled?: boolean;

src/types/runtime-options.ts

@@ -38,11 +38,12 @@ export interface FirecrackerOptions {
   sha256?: FirecrackerArtifactDigests;
 }
 
-// ─── Cloud Hypervisor (foundation only — no runnable backend yet) ──────────
+// ─── Cloud Hypervisor (v53.0 preview lifecycle backend) ────────────────────
 //
-// This configuration surface exists so callers can pin trusted artifacts and
-// round-trip config today. It is intentionally NOT registered as a
-// selectable `--container-runtime` value and has no lifecycle backend: see
+// This configuration surface pins trusted artifacts and configures the
+// Cloud Hypervisor microVM runtime. It is selectable via
+// `--container-runtime cloud-hypervisor` (gated behind explicit
+// `--cloud-hypervisor-preview` opt-in): see
 // `src/cloud-hypervisor/preflight.ts` for artifact/host validation and
 // `guest/cloud-hypervisor/` for the guest artifact pipeline. GitHub-hosted
 // Ubuntu x86_64 KVM runners are the only supported host target.
@@ -61,11 +62,11 @@ export interface CloudHypervisorArtifactDigests {
 }
 
 /**
- * Foundational configuration for a future Cloud Hypervisor microVM runtime.
+ * Cloud Hypervisor v53.0 preview microVM runtime settings.
  *
- * There is no lifecycle backend for this runtime yet — it cannot be selected
- * via `--container-runtime` and `previewEnabled` only gates config
- * acceptance/validation, not workload execution.
+ * Selectable via `--container-runtime cloud-hypervisor`, gated behind
+ * explicit `--cloud-hypervisor-preview` opt-in. Supported only on
+ * GitHub-hosted Ubuntu x86_64 KVM runners.
  */
 export interface CloudHypervisorOptions {
   previewEnabled: boolean;
@@ -241,10 +242,11 @@ export interface RuntimeOptions {
   firecracker?: FirecrackerOptions;
 
   /**
-   * Cloud Hypervisor microVM foundation settings (config/artifacts only).
+   * Cloud Hypervisor v53.0 preview microVM runtime settings.
    *
-   * There is no lifecycle backend yet; this cannot be selected as a
-   * `--container-runtime` value.
+   * Selectable via `--container-runtime cloud-hypervisor`, gated behind
+   * explicit `--cloud-hypervisor-preview` opt-in. Supported only on
+   * GitHub-hosted Ubuntu x86_64 KVM runners.
    */
   cloudHypervisor?: CloudHypervisorOptions;
 }