Upgrade and Migration Tests#

Post-build gate workflows for bootc image repos. Both workflows are part of the
projectbluefin/actions reusable workflow catalog.

Contents#

• Upgrade test
• Migration test
• Dakota (Path 2 only consumer)
• Live consumer examples

Upgrade test#

A post-build gate: after your image is built and pushed, call this workflow with
the new image ref. It boots it in QEMU via projectbluefin/testsuite and runs the
lifecycle suite — upgrade, reboot, rollback, /etc persistence, and idempotency.
Only if the gate passes should the image be promoted or tagged stable.

Minimal wiring — build → gate → promote#

jobs:
  build:
    # ... your build steps ...
    outputs:
      image: ${{ steps.push.outputs.registry-path }}/your-image
      digest: ${{ steps.push.outputs.digest }}

  upgrade-test:
    needs: build
    uses: projectbluefin/actions/.github/workflows/upgrade-test.yml@v1
    permissions:
      contents: read
      packages: write
    with:
      image: ${{ needs.build.outputs.image }}@${{ needs.build.outputs.digest }}

  promote:
    needs: upgrade-test
    if: needs.upgrade-test.outputs.result == 'success'
    # ... move tag, cut release, etc. ...

Inputs reference#

Outputs reference#

What the lifecycle suite tests#

Source: tests/lifecycle/features/bootc.feature

Permissions required#

permissions:
  contents: read
  packages: write # testsuite pushes desktop screenshots as OCI artifacts

Migration test#

A cross-registry migration gate for the ublue-os/bluefin[-lts] → projectbluefin/bluefin[-lts] transition. Boots the source image in QEMU, switches to the target via bootc switch, and validates the full @migration scenario matrix from projectbluefin/testsuite.

Use this gate when validating that users migrating from the ublue-os registry to the projectbluefin registry land on a working system, including across the chunkah format boundary (legacy rpm-ostree rechunked layers → chunkah OCI-native layers).

Minimal wiring — build → migration gate → promote#

jobs:
  build:
    outputs:
      digest: ${{ steps.push.outputs.digest }}

  migration-test:
    needs: build
    uses: projectbluefin/actions/.github/workflows/migration-test.yml@v1
    permissions:
      contents: read
      packages: write
    with:
      source_image: ghcr.io/ublue-os/bluefin-lts:lts
      migration_target: ghcr.io/projectbluefin/bluefin-lts@${{ needs.build.outputs.digest }}

  promote:
    needs: migration-test
    if: needs.migration-test.outputs.result == 'success'

Inputs reference#

Outputs reference#

Migration scenarios validated#

Source: tests/lifecycle/features/migration.feature

Dakota (Path 2 only consumer)#

dakota is structurally different from all other consumers — its image is produced by bst build oci/bluefin.bst inside a pinned bst2 container, not podman build of a Containerfile. It is a Path 2 only consumer, permanently. The full reusable workflow (reusable-build.yml) will never apply.

What applies to dakota#

What must never be touched#

• BST-domain composites (check-bst2-pin, generate-bst-ci-config) remain local to dakota
• BST remote CAS (cache.projectbluefin.io) is outside the shared caching model
• bst2 container SHA is pinned via check-bst2-pin — preserve this
• Never attempt to fit dakota into reusable-build.yml
• Never replace BST with rpm-ostree/Containerfile

Dakota push-image usage#

- uses: projectbluefin/actions/bootc-build/push-image@v1
  id: push
  with:
    image-name: dakota # or dakota-nvidia
    tags: "${{ needs.setup.outputs.sha }}"
    compression-format: zstd # BST exports plain OCI, not zstd:chunked
    github-token: ${{ secrets.GITHUB_TOKEN }}

Live consumer examples#

bluefin (Path 1 — extended validate-pr)#

bluefin opts into all three optional validate-pr inputs:

- uses: projectbluefin/actions/bootc-build/validate-pr@v1
  with:
    shellcheck-glob: "build_files/**/*.sh"
    system-files-shellcheck-glob: "system_files/**/*.sh"
    enable-desktop-file-validate: "true"
    check-submodule-drift: "true"

Hook scripts that source a runtime-only path (e.g. /usr/lib/ublue/setup-services/libsetup.sh) must include # shellcheck source=/dev/null on the source line to silence SC1091 in CI.

bluefin-lts (Path 2 — CentOS Stream 10)#

bluefin-lts uses CentOS Stream 10 (non-Fedora base) and cannot use the full reusable workflow. Key overrides:

This is the reference implementation for any bootc image repo that diverges from the bluefin path convention.

When to Use#

Use this skill when:

• Adding or configuring the upgrade-test.yml post-build gate workflow in a bootc image repository.
• Configuring migration-test.yml to test bootc switch transitions across container registries.
• Troubleshooting failures during QEMU virtual machine lifecycle testing (upgrade, rollback, idempotency, or /etc state persistence).
• Implementing Path 2 à la carte action adoption for non-standard image repositories (such as Dakota or Bluefin-LTS).

When NOT to Use#

Do not use this skill to:

• Test Python scripts or unit-level action logic (use testing.md).
• Run initial build pipelines or configure Justfile build recipes (use consumer-guide.md and reusable-workflow.md).
• Modify the QEMU testsuite test definitions themselves (these live in projectbluefin/testsuite).

Core Process#

1. Build and push artifact: Complete the container image build and obtain the immutable digest output.
2. Wire upgrade-test workflow: Add a job invoking projectbluefin/actions/.github/workflows/upgrade-test.yml@v1 passing the image digest.
3. Configure suites and options: Set test suites (default lifecycle), flatpak screenshot lists, or native app flags as required by the image.
4. Gate promotion: Ensure promotion jobs depend on upgrade-test output (needs.upgrade-test.outputs.result == 'success').
5. Inspect failure artifacts: If QEMU tests fail, download testsuite logs and screenshots from GitHub Actions artifacts for triage.

Common Rationalizations#

Red Flags#

• Promoting an image to :stable without gating on successful upgrade-test execution.
• Invoking upgrade-test with a mutable tag instead of a verified image digest.
• Missing packages: write permission on caller jobs when testsuite needs to upload screenshot artifacts.
• Attempting to force non-Fedora or custom build systems into Path 1 workflows.

Verification#

• upgrade-test.yml is invoked with an exact @sha256:... image digest.
• Caller permissions include packages: write and contents: read.
• Promotional steps execute only when needs.upgrade-test.outputs.result == 'success'.
• Test artifacts (logs, screenshots) are verified on test completion.