uefi-boot

name	uefi-boot
version	1.0
last_updated	2026-07-20
id	uefi-boot
one_line_purpose	Add or debug UEFI/OVMF reboot test paths.
entry_point	docs/skills/test-authoring/uefi-boot/SKILL.md
category	test-authoring
mcp_compliance_level	partial
status	active
dependencies	[]
tags	["uefi","ovmf","boot"]
description	UEFI/OVMF reboot testing guidance. Load when adding or debugging UEFI boot paths in the e2e workflows.
metadata	{"type":"pattern","audience":"agents","maturity":"stable"}

UEFI Boot via OVMF + systemd-boot

Load when: working on migration tests that require VM reboots, modifying the QEMU boot pipeline, or debugging UEFI/systemd-boot issues in CI.

Why UEFI boot matters

The existing e2e.yml uses direct kernel boot (-kernel/-initrd/-append). This extracts vmlinuz and initramfs at disk-setup time and passes them directly to QEMU. The VM always boots the same kernel — rebooting after bootc switch still boots the original deployment because QEMU re-uses the same kernel args.

Migration tests need the VM to boot the new deployment after bootc switch + reboot. UEFI boot via OVMF + systemd-boot solves this: systemd-boot reads BLS (Boot Loader Specification) entries from the disk and picks the highest-priority entry, which is the staged deployment after a switch.

Disk layout (bootc install to-disk --bootloader systemd)

Partition	Type	Mount point	Contents
p1	EFI System	/boot/efi	EFI/BOOT/BOOTX64.EFI (systemd-boot fallback binary), EFI/systemd/systemd-bootx64.efi
p2	xbootldr	/boot	loader/loader.conf, loader/entries/*.conf (BLS entries), kernel + initramfs per deployment
p3	Linux filesystem (ext4)	/	ostree root (deployments, /var, etc.)

BLS entries live in p2 (/boot/loader/entries/), not p1.

OVMF variant

Use OVMF_CODE_4M.fd (4MB pflash variant). The standard 2MB OVMF_CODE.fd works for simple UEFI boot but systemd-boot on Fedora writes more EFI variables than fit in the 2MB variable store.

On ubuntu-latest (GHA runner), install the ovmf package:

sudo apt-get install -y --no-install-recommends ovmf

Files:

• /usr/share/OVMF/OVMF_CODE_4M.fd — read-only firmware code
• /usr/share/OVMF/OVMF_VARS_4M.fd — writable variable store template