Skip to main content

support matrix

A re-base depends on six axes: backend, bootloader, LUKS, UKI, package manager and DE. This file records what the E2E matrix in e2e-tests.yml has proven about each axis — and refuses to record anything else.

The evidence rule​

Every status below carries its proof. There are exactly three statuses:

  • PROVEN — green on a main E2E run, cited by run id and date. Green on a PR branch is signal, not proof: PR code is not the product.
  • RED — red on a main E2E run, cited the same way. A red cell proves "does not work here". It does not prove "cannot work". Until you triage it, the cause can be the route, the harness or the image.
  • UNPROVEN — no cell, or no green on main. Unknown. Do not write "supported", "unsupported", "works" or "does not work" about these. This applies to docs, TUI copy and refusal messages. The honest word is "unknown", plus what would prove it.

Reference runs used below (both e2e-tests.yml):

  • main 33891928677 (2026-09-04): the last main run when we wrote this. It shows all gating cells green, except LVM-on-LUKS (red).
  • PR 36215098705 (2026-09-26): recent branch run, cited only to show flakiness where a cell disagrees with main.

Non-gating cells disagree between runs (image-swap, opensuse, one tunaOS cell each flipped). A status changes only on a new main run. When you update this file, update the reference runs above.

Unit tests prove only pure logic, for example route tables, karg filters and ESP classifiers. They never move a status past UNPROVEN here. The claim is that the system boots, and only a cell that boots proves it.

Backend (source × target route)​

Source of truth for the table shape: rebase_plan.rs ROUTES.

RouteStrategyStatusProof
ostree → composefsCoreMigrationPROVENbluefin -> dakota btrfs + ext4 cells green on main 33891928677 (gating)
composefs → composefsImageSwapRED (main); green once on a PR branchdakota -> utah red on main 33891928677, green on PR 36215098705 — flaky, unproven
ostree → ostreeOstreeDeployPROVENbluefin ostree re-base green on main 33891928677 (gating)
composefs → ostreeOstreeInstallREDdakota -> fedora-bootc red on main 33891928677 and on PR 36215098705 — untriaged
package → ostreePackageInstallUNPROVEN, no implementationreadiness and hardware reports exist, but #373 has not implemented the install and #380 has no cell

What RED means for the two red routes: nobody triaged the failure, so this file makes no claim about why. The image-swap red does not prove "Utah cannot boot composefs". The OstreeInstall red does not prove that the route has a defect. The cause of each can be the harness or the image. Triage first, claim after.

Route availability by frontend (mechanism fact, not a support claim):

Routebootc-migratebootc-rebaseTUI wizard
CoreMigration--target-image-t … (auto)full wizard
ImageSwapautomatic fallback when already composefs-t … --target-backend composefssame wizard, swap path
OstreeDeployno-t … --target-backend ostree on ostree hostsno
OstreeInstallno (--target-backend does not exist)-t … --target-backend ostree on composefs hostsno
PackageInstallnopackage hosts get a read-only --dry-run readiness preview; live install refuses (#373)OSTree-only target picker and read-only readiness preview

Package-based source hosts​

These rows are separate from the general route table. Detection of rpm, dpkg, or pacman plus the readiness checks does not prove that a package host can migrate or boot. A row stays UNPROVEN until its cell turns green on main. Issue #380 owns these cells. A green Fedora row does not promote Ubuntu, Debian, or Arch. A green UEFI/ext4 row does not promote btrfs, XFS, or BIOS.

SourcePackage databaseRoot filesystemBoot modeStorage stackStatusProof needed
Fedora Workstationrpmbtrfs subvolumeUEFIplainUNPROVENFedora Workstation → Bluefin cell green on main
Fedora Cloudrpmext4UEFIplainUNPROVENfirst #380 Fedora Cloud → fedora-bootc cell green on main
Fedora ServerrpmXFSUEFIplainUNPROVENFedora Server → fedora-bootc cell green on main
Ubuntudpkgext4UEFIplainUNPROVENUbuntu cross-family cell green on main
Debiandpkgext4UEFIplainUNPROVENDebian cross-family cell green on main
Arch Linuxpacmanext4UEFIplainUNPROVENArch cross-family cell green on main
Fedora, Ubuntu, Debian or Archmatching database abovebtrfs, XFS or ext4BIOS/CSMplainUNPROVEN; preflight refusesper-distribution BIOS cell plus implementation that passes preflight
Fedora, Ubuntu, Debian or Archmatching database abovebtrfs, XFS or ext4UEFILUKS and/or LVMUNPROVEN; preflight refusesper-layout cell plus implementation that passes preflight

Package-host readiness now allows only UEFI, btrfs/XFS/ext4, and no LUKS/LVM. That gate does not claim support. PackageInstall alone cannot make a row PROVEN. The software report (#377), rollback entry (#374), guided commit (#378), and first-boot verification (#379) are not ready.

Bootloader​

CombinationStatusProof
CoreMigration → systemd-boot (UEFI)PROVENevery green CoreMigration cell boots it (main 33891928677)
CoreMigration → GRUB2 (--bootloader grub2)UNPROVENno cell sets it (grub.rs is a placeholder; the logic lives in phase5_setup_bootloader with no E2E)
KeepSource on OstreeDeploy (GRUB stays GRUB)PROVENgating bluefin ostree re-base green on main 33891928677
KeepSource on ImageSwap (systemd-boot stays)UNPROVENroute is RED; nothing separable is proven
OstreeInstall GRUB-first + "Linux Boot Manager" rollback entryUNPROVENcell is RED; bootloader vs route failure not separated
Standalone migrate-bootloader (#65/#382)IMPLEMENTED; E2E cell addedbootloader-trial stages GRUB2 → systemd-boot with a one-boot trial, kernel-install resync, guarded promotion, and undo; the cell is the pending live proof, while real-hardware firmware behavior remains outside OVMF
BIOS/CSM (non-UEFI) hosts, any routeUNPROVENharness boots OVMF/UEFI only; no BIOS cell
GRUB2-BLS as an endpoint (openSUSE default)UNPROVENreference note in docs/references.md only

LUKS / disk layout​

CombinationStatusProof
CoreMigration, plain (btrfs, ext4)PROVENgating cells green on main 33891928677
CoreMigration, LUKS root (xfs+crypt, TPM2 unlock)PROVENgating cell green on main 33891928677
CoreMigration, LVM-on-LUKS + separate /varRED (main); green on a PR branchred on main 33891928677, green on PR 36215098705 — flaky, unproven
CoreMigration, encrypted /bootUNPROVENE2E layout assumes unencrypted /boot; no code, no cell
CoreMigration, btrfs-on-LUKSUNPROVENno code path, no cell
CoreMigration, detached LUKS headersUNPROVENno code path, no cell
CoreMigration, passphrase (non-TPM2) unlockUNPROVENharness unlocks via swtpm only; no sendkey/passphrase cell
LUKS of any kind on ImageSwap / OstreeDeployUNPROVENno cells; both rely on bootc switch native behavior, which no cell exercises under encryption
LUKS of any kind on OstreeInstallUNPROVENcarry_over_kargs keeps rd.luks.*/rd.lvm.lv in code, but the route's only cell is RED on unencrypted disk — encryption adds an unproven axis to a red route

UKI (boot artifact format)​

CombinationStatusProof
BLS Type 1 (loader/entries/*.conf + kernel/initrd on ESP) for composefsPROVENevery green composefs-boot cell boots it (main 33891928677)
UKI Type 2 (.efi unified image) for composefsUNPROVEN, no implementationzero uki matches in crates/; SPECIFICATION.md §3 plans it, nothing builds/installs/detects .efi artifacts
Upstream auto-detection rule (UKI + systemd-boot + no bootupd ⇒ composefs backend)reference onlycited in docs/references.md from bootc docs; not implemented as logic anywhere

Consequence for the Utah question: "composefs-capable" in scan output means prepare-root.conf enables composefs. It does not tell if the initramfs has the composefs module (the scan shows that Utah's does not). It also tells nothing about UKI. The RED/flaky image-swap cell must show if Utah boots as a composefs deployment. Refer to the backend table, not the scan.

Package manager (lineage input)​

The scanner reads each image's package manager (scan.rs BaseInfo). Two images with the same manager are one family, whatever the value of ID_LIKE. A pair with no evidence (Dakota ships no manager) gives a warning and keeps the standard merge (cross_family.rs).

CombinationStatusProof
Different manager, cross-family policy (→ opensuse-bootc)RED (latest); green on maingreen on main 33891928677, red on PR 36215098705 — flaky, unproven
Same-manager shortcutUNPROVEN at E2E levelunit-tested only; no cell isolates it
No-manager Unknown path (Dakota as source)UNPROVEN at E2E levelexercised only inside RED/flaky cells (image-swap, OstreeInstall)

DE (desktop environment)​

CombinationStatusProof
Same DE, any green routePROVENgating cells (all GNOME→GNOME) green on main 33891928677
Cross-DE GNOME → KDE, no --de-migrate (aurora)PROVEN (non-gating)green on main 33891928677
Cross-DE + --de-migrate stash/restore (tunaOS ring, 4 cells)PROVEN (non-gating)all four green on main 33891928677
--de-migrate on CoreMigration / ImageSwap / OstreeInstallUNPROVEN--de-migrate is exercised only in ostree-rebase E2E mode

The Dakota → Utah migration, per axis​

The concrete target: Dakota (composefs, systemd-boot, BLS-1, btrfs-on-LUKS, no package manager, GNOME) → Utah (ostree, GRUB via bootupd, GNOME).

AxisStatus for this pair
Backend (composefs → ostree)RED with fedora-bootc:44; no cell with Utah — unproven for this pair
Bootloader (systemd-boot → GRUB-first + rollback entry)UNPROVEN (only exercised inside the RED cell)
LUKS (btrfs-on-LUKS source)UNPROVEN (no btrfs-on-LUKS cell on any route)
UKIN/A — ostree target boots BLS/GRUB, not a UKI question
Package manager (none → ?)UNPROVEN (Unknown-lineage path, no green E2E)
DE (GNOME → GNOME)same-DE path, proven on other routes only

Real-host evidence (2026-09-29/30) does not change the tags above. Only a green main run can change them. On a developer laptop, the route staged with exit 0 and the host booted Utah. The source was Dakota (composefs, systemd-boot, btrfs-on-LUKS). The target was utah:testing. Two manual steps were necessary, and issues track both:

  • GRUB cannot unlock the LUKS root. The boot used a manual ESP kernel and a BLS ostree= entry through systemd-boot (#305).
  • The carried /var needed an ownership/mtime repair (#308, fixed on ux/ostreeinstall-progress) and a new machine-id (#309).

Overall: UNPROVEN. On a real host today, it is an experiment, not a supported migration. What would promote it, in order:

  1. Triage the RED dakota -> fedora-bootc OstreeInstall cell — a green route with a small target first.
  2. Add a dakota -> utah OstreeInstall cell (or re-target the fedora-bootc one once Utah fits the job time budget) and get it green.
  3. Decide what to do with the image-swap cell. If Utah-as-composefs stays RED, stop the claim for that route for Utah. Do not keep a red non-gating cell as decoration.
  4. LUKS coverage for the route last — it is the hardest axis to add (swtpm + fisherman recipe per docs/luks-testing.md).

Maintenance​

  • This file follows main E2E runs, not PR runs. After a green main run, update the reference runs and flip whatever it proved.
  • A "supported" claim anywhere (README, TUI copy, refusal text) must name its cell here. No cell, no claim — write "unknown" and link the gap.
  • A flaky cell (green/red across runs) keeps the worse status. It keeps it until you fix the flake or the cell stays green.