Skip to content
Merged
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
1 change: 1 addition & 0 deletions docs/skills/ci-ops/e2e-workflow/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -497,3 +497,4 @@ Load these when you hit the specific topic:
- [Installer suite assertions, and why an env-var gate made one unreachable.](references/installer-suite.md)
- [Migration inputs `migration-target` / `extra-tags` and the startup_failure they cause when missing.](references/migration-inputs.md)
- [GNOME OS guest lane for the developer extension-validation service and its mandatory gate.](references/gnome-extensions-validation.md)
- [Which units the fast e2e lane masks, why, and which still need a startup-qualification lane.](references/startup-service-inventory.md)
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
---
name: startup-service-inventory
description: "Which units the fast e2e lane masks, why, and which ones still need a startup-qualification lane."
metadata:
type: reference
audience: agents
maturity: draft
---
# Startup-service inventory

The fast hosted lane in `.github/workflows/e2e.yml` masks units before first
boot, through `systemd.mask=` in `KERNEL_ARGS` and through `/dev/null`
symlinks in each deployment's `/etc/systemd/system/`. A green fast-lane run
therefore says nothing about those units. `startup_service_inventory.yaml`
(repo root) classifies every masked unit:

| Category | Meaning | Fast-lane result counts as qualification? |
|---|---|---|
| `startup_contract` | Shipped first-boot, update or health path that a profile enables | No. Needs a representative startup lane (#1025) |
| `vm_inapplicable` | Needs hardware or a radio hosted QEMU lacks | Not applicable |
| `ci_noise` | Shipped background service outside first boot, masked for speed | No, but not a startup gap |

`tests/unit/test_startup_service_inventory.py` fails when a unit is masked
without an entry, when an entry is no longer masked, or when an entry's
`mask_sites` disagree with the workflow. Changing a mask in `e2e.yml` means
updating the inventory in the same PR.

## Gotchas found while building the inventory

- The symlink loop appends `.service`, `.socket`, `.path` and `.timer` to every
token. A bare token (`cups`) already masks `cups.socket` and `cups.path`;
dotted tokens (`cups.path`, `avahi-daemon.socket`) only create bogus
`*.path.service` names.
- `cups.browsed.service` is not a real unit. Fedora ships
`cups-browsed.service`, which neither mask site touches.
- Bluefin and Bluefin LTS enable `podman-auto-update.timer` with
`systemctl --global`, i.e. for user managers. Both mask sites act on the
system manager, so the shipped user timer is probably still active. Observe
the user unit before claiming it is covered or masked.
- The fast lane replaces `flatpak-preinstall.service` with a runner-cached
sideload of `flatpak-app-list.txt`, and `brew-setup.service` with direct
`brew install`/dnf installs. Those substitutes must not satisfy startup
assertions.

## Still open (#1025)

The representative startup lane itself (new job or input, bounded deadlines
per `startup_contract` unit, Flatpak remotes/apps/permissions from the shipped
preinstall, greenboot with a real boot-counting path per #706) is a new CI
lane and needs maintainer design approval before implementation.
4 changes: 4 additions & 0 deletions docs/skills/test-authoring/suite-map/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -225,6 +225,10 @@ tag precedence order: `@quarantine` > `@hardware_blocked` > `@future` > `@pendin
| `ujust toggle-devmode` group mutation | Medium | Non-interactive contract now exists: `bctl devmode --enable/--disable` (bluefinctl), which `toggle-devmode` execs to when `bctl` is present. Presence + idempotent state-check are covered in `common_devmode.feature`, gated `@requires_bctl` because bluefinctl is a Homebrew preinstall and `brew-setup.service` is masked in QEMU CI (#487). The actual group-mutating branch calls `pkexec usermod`, which requires an authentication agent bound to a real login session — unavailable over plain SSH. Scenario stays `@pending @wip`. Next step: a CI/lab-side non-interactive polkit or session-agent contract for `pkexec`; tracked in `projectbluefin/testsuite#500`. |
| uupd conditional suppression | Medium | Battery and metered-network checks are not covered: uupd reads UPower and NetworkManager system-bus properties, while testsuite has no supported isolated state-injection contract. Do not use `/sys/class/power_supply` or GNOME proxy settings as substitutes. Next step: add a lab/image-owned simulation hook, then cover the upstream `/etc/uupd/config.json` contract. |

Fast-lane service masks are classified in `startup_service_inventory.yaml`
(see the [startup-service inventory](../../ci-ops/e2e-workflow/references/startup-service-inventory.md)).
A `startup_contract` unit masked there is not qualified by a green fast-lane run.

### Skipped-coverage breakdown

Why the `@pending`/`@future` scenarios above cannot run today.
Expand Down
215 changes: 215 additions & 0 deletions startup_service_inventory.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,215 @@
# Startup-service inventory for the fast hosted QEMU lane (.github/workflows/e2e.yml).
#
# e2e.yml masks units twice before first boot:
# - kernel_args: `systemd.mask=<unit>` entries in KERNEL_ARGS
# - deployment_symlink: `/dev/null` symlinks written into each deployment's
# /etc/systemd/system/ by the "Mask CI-irrelevant services"
# loop. The loop appends .service/.socket/.path/.timer to
# every token, so a bare token `cups` masks cups.socket
# and cups.path too, while a dotted token such as
# `cups.path` only yields `cups.path.service` and masks
# nothing extra.
#
# Every masked unit must have exactly one entry here, and every entry must still
# be masked; tests/unit/test_startup_service_inventory.py enforces both ways.
#
# Categories:
# startup_contract — a shipped first-boot/update/health path that at least one
# profile enables. The fast lane does NOT qualify it; a
# representative startup lane must run it (#1025).
# vm_inapplicable — needs hardware or a radio that hosted QEMU does not have.
# Masking is deliberate and is not a coverage gap.
# ci_noise — a shipped background service outside the first-boot
# contract, masked only to cut boot time or network use.
#
# Profiles are the image families whose build enables the unit (evidence
# cites the enabling build file). `all` means it is part of the shared base.

units:
# --- startup_contract -------------------------------------------------------
brew-setup.service:
category: startup_contract
mask_sites: [kernel_args]
profiles: [bluefin, bluefin-lts, bazzite]
evidence:
- ublue-os/bluefin build_files/base/17-cleanup.sh (systemctl enable brew-setup.service)
- ublue-os/bluefin-lts build_scripts/40-services.sh (systemctl enable brew-setup.service)
- ublue-os/bazzite Containerfile (systemctl enable brew-setup.service)
fast_lane_substitute: e2e.yml installs brew CLI tools directly, or falls back to dnf
blocks: developer brew/bctl/mise scenarios, common ujust changelogs (#487)

flatpak-preinstall.service:
category: startup_contract
mask_sites: [kernel_args]
profiles: [bluefin, bluefin-lts, aurora]
evidence:
- projectbluefin/common system_files/shared/usr/lib/systemd/system/flatpak-preinstall.service
- ublue-os/bluefin build_files/base/17-cleanup.sh (systemctl enable flatpak-preinstall.service)
- ublue-os/aurora system_files/shared/usr/lib/systemd/system-preset/89-aurora.preset
fast_lane_substitute: e2e.yml sideloads flatpak-app-list.txt from a runner cache into the system installation
blocks: smoke flatpak_permissions system-wide installs (x39), common flatpak model/state and services scenarios

NetworkManager-wait-online.service:
category: startup_contract
mask_sites: [kernel_args]
profiles: [all]
evidence:
- flatpak-preinstall.service is ordered After=/Wants=network-online.target, which this unit gates
fast_lane_substitute: none; network-online.target is reached without waiting for a connection
blocks: an honest ordering for flatpak-preinstall.service

firewalld.service:
category: startup_contract
mask_sites: [kernel_args]
profiles: [bluefin-lts]
evidence:
- ublue-os/bluefin-lts build_scripts/40-services.sh (systemctl enable firewalld.service)
fast_lane_substitute: none; firewall state is never observed

podman-auto-update.service:
category: startup_contract
mask_sites: [kernel_args, deployment_symlink]
profiles: [bluefin, bluefin-lts]
evidence:
- ublue-os/bluefin build_files/base/17-cleanup.sh (systemctl --global enable podman-auto-update.timer)
- ublue-os/bluefin-lts build_scripts/40-services.sh (systemctl --global enable podman-auto-update.timer)
fast_lane_substitute: none
notes: >-
The images enable the user-level timer (--global). Both mask sites target
the system manager, so the shipped user timer is probably untouched; the
startup lane must observe the user unit, not assume the mask covers it.

podman-auto-update.timer:
category: startup_contract
mask_sites: [kernel_args, deployment_symlink]
profiles: [bluefin, bluefin-lts]
evidence:
- see podman-auto-update.service
fast_lane_substitute: none

greenboot-healthcheck.service:
category: startup_contract
mask_sites: [kernel_args]
profiles: [bazzite]
evidence:
- ublue-os/bazzite Containerfile (systemctl enable greenboot-healthcheck.service)
fast_lane_substitute: none
notes: >-
Automatic rollback needs a real bootloader boot-counting path; the fast
lane boots a direct kernel, so it cannot stand in for it (#706).

greenboot-set-rollback-trigger.service:
category: startup_contract
mask_sites: [kernel_args]
profiles: [bazzite]
evidence:
- ublue-os/bazzite Containerfile (systemctl enable greenboot-set-rollback-trigger.service)
fast_lane_substitute: none
notes: see greenboot-healthcheck.service

bazzite-hardware-setup.service:
category: startup_contract
mask_sites: [kernel_args]
profiles: [bazzite]
evidence:
- ublue-os/bazzite system_files/desktop/shared/usr/lib/systemd/system/bazzite-hardware-setup.service
- ublue-os/bazzite Containerfile (systemctl enable bazzite-hardware-setup.service)
fast_lane_substitute: none
notes: >-
Runs on every boot, including generic hardware. The startup lane must say
which of its branches are hardware-specific before treating any as inapplicable.

# --- vm_inapplicable --------------------------------------------------------
wpa_supplicant.service:
category: vm_inapplicable
mask_sites: [kernel_args]
reason: no Wi-Fi device in hosted QEMU; SLIRP user networking only

bluetooth.service:
category: vm_inapplicable
mask_sites: [deployment_symlink]
reason: no Bluetooth controller in hosted QEMU

blueman-mechanism.service:
category: vm_inapplicable
mask_sites: [kernel_args, deployment_symlink]
reason: Bluetooth manager helper; no Bluetooth controller in hosted QEMU

ModemManager.service:
category: vm_inapplicable
mask_sites: [deployment_symlink]
reason: no cellular modem in hosted QEMU

fwupd.service:
category: vm_inapplicable
mask_sites: [deployment_symlink]
reason: no updatable device firmware in hosted QEMU (bluefin-lts enables it)

colord.service:
category: vm_inapplicable
mask_sites: [deployment_symlink]
reason: no calibrated display or printer colour profile to manage

systemd-udev-settle.service:
category: vm_inapplicable
mask_sites: [kernel_args]
reason: times out (~125s) waiting for hardware that QEMU does not present

# --- ci_noise ---------------------------------------------------------------
cups.service:
category: ci_noise
mask_sites: [kernel_args, deployment_symlink]
reason: printing is covered by its own suite, not by first-boot startup

cups.path:
category: ci_noise
mask_sites: [kernel_args, deployment_symlink]
reason: see cups.service

cups.socket:
category: ci_noise
mask_sites: [kernel_args, deployment_symlink]
reason: see cups.service

cups.browsed.service:
category: ci_noise
mask_sites: [kernel_args, deployment_symlink]
reason: network printer discovery; see cups.service
notes: >-
Fedora names this unit cups-browsed.service (hyphen). Neither mask site
matches that name, so the real service is not masked in the fast lane.

avahi-daemon.service:
category: ci_noise
mask_sites: [kernel_args, deployment_symlink]
reason: mDNS discovery has no peers on SLIRP networking

avahi-daemon.socket:
category: ci_noise
mask_sites: [kernel_args, deployment_symlink]
reason: see avahi-daemon.service

malcontent-webd.service:
category: ci_noise
mask_sites: [kernel_args]
reason: parental-controls web filter downloads data on boot

malcontent-webd-update.service:
category: ci_noise
mask_sites: [kernel_args]
reason: see malcontent-webd.service

malcontent-control.service:
category: ci_noise
mask_sites: [kernel_args, deployment_symlink]
reason: see malcontent-webd.service

speech-dispatcherd.service:
category: ci_noise
mask_sites: [kernel_args]
reason: speech synthesis daemon, not part of startup

gnome-remote-desktop.service:
category: ci_noise
mask_sites: [kernel_args, deployment_symlink]
reason: remote desktop server, not part of startup
Loading
Loading