Skip to content
Closed
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
275 changes: 275 additions & 0 deletions .github/workflows/iso.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,275 @@
name: Build, test, and publish Utah ISO

run-name: >-
Utah ISO validation for ${{ github.event.workflow_run.head_sha || inputs.image || 'manual' }}

on:
workflow_run:
workflows: ["Post-Testing E2E"]
types: [completed]
branches: [testing]
workflow_dispatch:
inputs:
image:
description: "Exact x86_64 image reference to test (must use @sha256:...)"
required: false
type: string
source_run_id:
description: "Successful Build Utah run containing image digest artifacts"
required: false
type: string
encryption:
description: "Installation encryption mode (luks or none)"
required: false
default: "luks"
type: choice
options:
- luks
- none

permissions: {}

concurrency:
group: utah-iso-${{ github.event.workflow_run.head_sha || github.run_id }}
cancel-in-progress: false

jobs:
resolve-image:
name: Resolve exact candidate image
if: github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success'
runs-on: ubuntu-24.04
permissions:
actions: read
contents: read
packages: read
outputs:
image: ${{ steps.resolve.outputs.image }}
payload_ref: ${{ steps.resolve.outputs.payload_ref }}
source_digest: ${{ steps.resolve.outputs.source_digest }}
steps:
- name: Resolve exact x86_64 image digest
id: resolve
env:
GH_TOKEN: ${{ github.token }}
DISPATCH_IMAGE: ${{ inputs.image }}
DISPATCH_RUN_ID: ${{ inputs.source_run_id }}
EVENT_SHA: ${{ github.event.workflow_run.head_sha }}
REPOSITORY: ${{ github.repository }}
OWNER: ${{ github.repository_owner }}
run: |
set -euo pipefail
build_run_id=manual
image="${DISPATCH_IMAGE:-}"
source_digest=""

if [[ -n "$image" ]]; then
if [[ ! "$image" =~ ^ghcr\.io/[^/]+/utah@sha256:[0-9a-f]{64}$ ]]; then
echo "image must be an exact ghcr.io/<owner>/utah@sha256:<digest> reference" >&2
exit 1
fi
source_digest="${image##*@}"
else
build_run_id="${DISPATCH_RUN_ID:-}"
if [[ -z "$build_run_id" && -n "${EVENT_SHA:-}" ]]; then
build_run_id="$(gh run list \
--repo "$REPOSITORY" \
--workflow build.yml \
--commit "$EVENT_SHA" \
--event push \
--status success \
--limit 1 \
--json databaseId \
--jq '.[0].databaseId')"
fi
[[ -n "$build_run_id" ]] || {
echo "No successful Build Utah run was supplied or found for ${EVENT_SHA:-the manual run}" >&2
exit 1
}

digest_dir="${RUNNER_TEMP}/utah-build-digests"
mkdir -p "$digest_dir"
gh run download "$build_run_id" \
--repo "$REPOSITORY" \
--pattern 'image-digest-testing-*' \
--dir "$digest_dir"

mapfile -t digests < <(
grep -RhsE '^utah=sha256:[0-9a-f]{64}$' "$digest_dir" \
| cut -d= -f2- \
| sort -u
)
[[ "${#digests[@]}" -eq 1 ]] || {
printf 'Expected exactly one main utah digest, found %s\n' "${#digests[@]}" >&2
printf '%s\n' "${digests[@]}" >&2
exit 1
}
source_digest="${digests[0]}"
image="ghcr.io/${OWNER,,}/utah@${source_digest}"
fi

payload_ref="ghcr.io/${OWNER,,}/utah:ci-$GITHUB_RUN_ID"
{
echo "image=$image"
echo "payload_ref=$payload_ref"
echo "source_digest=$source_digest"
} >> "$GITHUB_OUTPUT"
echo "Candidate: ${image}"
echo "Payload reference inside ISO: ${payload_ref}"
echo "Build run: ${build_run_id}"

iso-e2e:
name: Build, install, and boot x86_64 UEFI ISO
needs: resolve-image
if: needs.resolve-image.result == 'success'
runs-on: ubuntu-24.04
timeout-minutes: 360
permissions:
contents: read
packages: read
env:
IMAGE: ${{ needs.resolve-image.outputs.image }}
PAYLOAD_REF: ${{ needs.resolve-image.outputs.payload_ref }}
SOURCE_DIGEST: ${{ needs.resolve-image.outputs.source_digest }}
ENCRYPTION_MODE: ${{ inputs.encryption || 'luks' }}
ISO_OUTPUT: ${{ github.workspace }}/.ci/utah-iso-output
ISO_PATH: ${{ github.workspace }}/.ci/utah-iso-output/utah-live.iso
E2E_WORK: ${{ github.workspace }}/.ci/utah-iso-output/e2e
steps:
- name: Checkout
uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5

- name: Install ISO and VM tooling
run: |
set -euo pipefail
sudo apt-get update
sudo apt-get install -y --no-install-recommends \
podman skopeo squashfs-tools xorriso dosfstools mtools \
qemu-system-x86 qemu-utils ovmf ffmpeg sshpass cryptsetup-bin
sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc
mkdir -p "$ISO_OUTPUT"
df -h /

- name: Pull exact candidate image
env:
GH_TOKEN: ${{ github.token }}
run: |
set -euo pipefail
echo "$GH_TOKEN" | podman login ghcr.io \
--username "$GITHUB_ACTOR" --password-stdin
podman pull "$IMAGE"
architecture="$(podman image inspect --format '{{.Architecture}}' "$IMAGE")"
case "$architecture" in
amd64|x86_64) ;;
*) echo "Expected an x86_64 image, got ${architecture}" >&2; exit 1 ;;
esac
echo "Pulled ${IMAGE} (${architecture})"

- name: Build UEFI ISO without publishing it
run: |
set -euo pipefail
mkdir -p "${RUNNER_TEMP}/utah-iso-stage"
UTAH_ISO_WORKDIR="${RUNNER_TEMP}/utah-iso-stage" \
bash iso/scripts/build-iso.sh \
"$IMAGE" "$ISO_PATH" "Utah Live" 1 "$PAYLOAD_REF" "$IMAGE"
test -s "$ISO_PATH"
xorriso -indev "$ISO_PATH" -report_el_torito plain \
| tee "${ISO_OUTPUT}/el-torito.txt"
grep -qi 'EFI' "${ISO_OUTPUT}/el-torito.txt"
sha256sum "$ISO_PATH" > "${ISO_OUTPUT}/utah-live.iso.sha256"
cat > "${ISO_OUTPUT}/candidate.txt" <<EOF
image=${IMAGE}
source_digest=${SOURCE_DIGEST}
payload_ref=${PAYLOAD_REF}
architecture=x86_64
firmware=UEFI
EOF
sed -i 's/^ //' "${ISO_OUTPUT}/candidate.txt"

- name: Run live, offline encrypted install, and installed graphical boot gates
run: |
set -euo pipefail
UTAH_E2E_ENCRYPTION="${ENCRYPTION_MODE}" \
UTAH_E2E_WORK="$E2E_WORK" \
bash iso/scripts/offline-e2e.sh "$ISO_PATH" "$PAYLOAD_REF" "$IMAGE"

- name: Validate retained gate evidence
if: success()
run: |
set -euo pipefail
test -s "$E2E_WORK/live-serial.log"
test -s "$E2E_WORK/installed-serial.log"
test -s "$E2E_WORK/e2e-summary.txt"
grep -q "encryption=${ENCRYPTION_MODE}" "$E2E_WORK/e2e-summary.txt"
grep -q "installed_marker=UTAH_INSTALLED_GRAPHICAL_OK" "$E2E_WORK/e2e-summary.txt"
grep -q "flatpaks_verified=true" "$E2E_WORK/e2e-summary.txt"
for label in live-desktop installed-desktop; do
if [[ ! -s "$E2E_WORK/screenshots/${label}.png" && \
! -s "$E2E_WORK/screenshots/${label}.ppm" ]]; then
echo "Missing ${label} screenshot evidence" >&2
exit 1
fi
done

- name: Write final ISO manifest
if: success()
env:
MANIFEST: ${{ github.workspace }}/.ci/utah-iso-output/manifest.json
run: |
set -euo pipefail
python3 - "$MANIFEST" "$ISO_PATH" "$IMAGE" "$SOURCE_DIGEST" "$PAYLOAD_REF" "$ENCRYPTION_MODE" <<'PY'
import hashlib
import json
import pathlib
import sys

manifest, iso, image, digest, payload, encryption = sys.argv[1:]
path = pathlib.Path(iso)
sha256 = hashlib.sha256()
with path.open("rb") as source:
for chunk in iter(lambda: source.read(1024 * 1024), b""):
sha256.update(chunk)
pathlib.Path(manifest).write_text(json.dumps({
"artifact": path.name,
"sha256": sha256.hexdigest(),
"architecture": "x86_64",
"firmware": "UEFI",
"source_image": image,
"source_digest": digest,
"embedded_payload": payload,
"encryption": encryption,
"live_marker": "UTAH_LIVE_READY",
"installed_marker": "UTAH_INSTALLED_GRAPHICAL_OK",
"flatpaks_verified": True,
"network": {
"live_control": "qemu-user-restrict-on",
"installed": "none",
},
}, indent=2) + "\n")
PY

- name: Publish production ISO and checksum
if: success()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
with:
name: utah-iso-x86_64-${{ github.run_id }}
path: |
${{ github.workspace }}/.ci/utah-iso-output/utah-live.iso
${{ github.workspace }}/.ci/utah-iso-output/utah-live.iso.sha256
${{ github.workspace }}/.ci/utah-iso-output/candidate.txt
${{ github.workspace }}/.ci/utah-iso-output/el-torito.txt
${{ github.workspace }}/.ci/utah-iso-output/manifest.json
${{ github.workspace }}/.ci/utah-iso-output/e2e/live-serial.log
${{ github.workspace }}/.ci/utah-iso-output/e2e/installed-serial.log
${{ github.workspace }}/.ci/utah-iso-output/e2e/e2e-summary.txt
${{ github.workspace }}/.ci/utah-iso-output/e2e/screenshots/
if-no-files-found: error
retention-days: 30

- name: Retain failed ISO diagnostics
if: failure()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
with:
name: utah-iso-failure-${{ github.run_id }}
path: ${{ github.workspace }}/.ci/utah-iso-output/
if-no-files-found: warn
retention-days: 14
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ just check-desktop-contract # in-image verifiers against a built image
just generate-bootable-image testing # bootc install to-disk -> output/bootable.raw
just boot-vm # QEMU/noVNC; confirm GDM + GNOME Shell render
just iso testing && just boot-iso # live ISO build + boot (see docs/skills/local-testing.md)
just iso-e2e # network-isolated live ISO install and graphical boot (LUKS/none)
```

`just check` is the gate CI runs first; a change that fails it fails the whole
Expand Down
19 changes: 19 additions & 0 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,13 @@ check:
bash -n iso/live/src/configure-live.sh
bash -n iso/live/src/install-flatpaks.sh
bash -n iso/scripts/build-iso.sh
test -f iso/scripts/offline-e2e.sh
bash -n iso/scripts/offline-e2e.sh
test -f iso/scripts/luks-unlock.py
python3 -m py_compile iso/scripts/luks-unlock.py
test -f tests/unit/test_luks_unlock.py
python3 -m unittest tests/unit/test_luks_unlock.py
grep -q 'cryptsetup' packages/utah.toml
python3 -m json.tool iso/live/src/etc/bootc-installer/images.json >/dev/null
python3 -m json.tool iso/live/src/etc/bootc-installer/recipe.json >/dev/null
grep -q 'org.bootcinstaller.Installer' iso/live/src/install-flatpaks.sh
Expand Down Expand Up @@ -369,6 +376,18 @@ boot-iso:
--volume "$iso:/boot.iso:ro" \
ghcr.io/qemus/qemu:latest

# Run network-isolated live ISO install and graphical boot E2E test in QEMU.
# Supports encryption="luks" (default) or encryption="none".
iso-e2e iso="" payload_ref="ghcr.io/projectbluefin/utah:testing" encryption="luks":
#!/usr/bin/env bash
set -euo pipefail
iso_path="{{ iso }}"
if [[ -z "$iso_path" ]]; then
iso_path="$(realpath "{{ base_dir }}/utah-live.iso")"
fi
test -f "$iso_path" || { echo "Missing ISO: $iso_path; run just iso" >&2; exit 1; }
UTAH_E2E_ENCRYPTION="{{ encryption }}" bash iso/scripts/offline-e2e.sh "$iso_path" "{{ payload_ref }}"

# Boot the installed Utah disk through QEMU-for-Docker. Open the printed URL
# and confirm GDM appears and the GNOME Shell desktop renders. The disk is
# mounted at /boot.img and -snapshot keeps the test disposable.
Expand Down
3 changes: 3 additions & 0 deletions docs/skills/ci-workflows.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,9 @@ each pinned to a SHA tagged `v1`:
- `.github/workflows/promote-testing-to-main.yml` -- pushes to `testing`, a
nightly cron, and manual dispatch.
- `.github/workflows/sync-main-to-testing.yml` -- every push to `main`.
- `.github/workflows/iso.yml` -- builds, tests, and publishes the production
x86_64 UEFI ISO after testing promotion, running offline LUKS-encrypted
installation and graphical boot gates in QEMU.

CI delegates builds, vulnerability reporting, SBOMs, keyless signatures,
provenance, caching, and rechunking to `projectbluefin/actions@v1` (originated
Expand Down
18 changes: 18 additions & 0 deletions docs/skills/local-testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,24 @@ just boot-iso # QEMU/noVNC live-session validation
just iso testing 1 # optional live-session SSH diagnostics (debug=1)
```

## Offline ISO and encrypted installation validation

The offline installer test validates the production ISO end to end in QEMU:
boots the live ISO, verifies the live graphical desktop, executes a network-isolated
installation from the embedded OCI payload onto a LUKS2 encrypted volume,
unlocks the encrypted disk via Plymouth (`luks-unlock.py`), and validates that
the installed deployment reaches the graphical target with default Flatpaks intact:

```bash
just iso testing 1
just iso-e2e output/utah-live.iso ghcr.io/projectbluefin/utah:testing luks
```

Key features:
- Supports `encryption="luks"` (default) or `encryption="none"`.
- `iso/scripts/luks-unlock.py` monitors QEMU serial and framebuffer screendumps to detect Plymouth's passphrase prompt and inject the unlock key.
- Captures serial logs (`live-serial.log`, `installed-serial.log`), framebuffer screenshots (`live-desktop.png`, `installed-desktop.png`), and retains failed disk images on error.

The result is `output/utah-live.iso`, assembled with systemd-boot, a
`UTAH_LIVE` dmsquash-live root, and a serial `UTAH_LIVE_READY` marker. It is
intended to prove live desktop boot first; bootc-installer/offline payload
Expand Down
10 changes: 6 additions & 4 deletions iso/live/Containerfile
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,14 @@
ARG SOURCE_IMAGE=localhost/utah:testing
FROM ${SOURCE_IMAGE}

# TARGET_IMAGE is the published image name recorded in the installer recipe
# and embedded offline store. SOURCE_IMAGE may be localhost for development;
# it must never leak into the released recipe.
# TARGET_IMAGE is the tag imported into the embedded offline store. The
# separately supplied TRACKING_IMAGE is the exact remote ref recorded for
# updates. SOURCE_IMAGE may be localhost for development; it must never leak
# into the released recipe.
ARG TARGET_IMAGE=ghcr.io/projectbluefin/utah:testing
ARG TRACKING_IMAGE=ghcr.io/projectbluefin/utah:testing
ARG DEBUG=0
ENV TARGET_IMAGE=${TARGET_IMAGE} DEBUG=${DEBUG}
ENV TARGET_IMAGE=${TARGET_IMAGE} TRACKING_IMAGE=${TRACKING_IMAGE} DEBUG=${DEBUG}

# Utah already carries dracut-live; systemd-boot is added only to the live
# environment because the installed image uses the Hummingbird bootloader.
Expand Down
Loading