| 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
