lib: Add --apply-staged flag for bootc upgrade

Add a new --apply-staged flag to bootc upgrade that allows users to
unlock a staged deployment created with --download-only without
checking for newer updates from the registry.

This provides a way to apply already-downloaded updates without
triggering a registry check, which is useful for scheduled maintenance
workflows where the update was downloaded earlier and should now be
applied at a scheduled time.

Usage:
  # Download update without applying
  bootc upgrade --download-only

  # Later: Apply the staged update (no registry check)
  bootc upgrade --apply-staged

  # Or: Apply staged update and reboot immediately
  bootc upgrade --apply-staged --apply

The flag conflicts with --check and --download-only as those operations
have different purposes. It can be combined with --apply to immediately
reboot after unlocking the staged deployment.

This commit also updates the documentation (upgrades.md) to describe
all three ways to apply a download-only update, and updates the
download-only test case (test-25) to use --apply-staged instead of
plain `bootc upgrade` when clearing the download-only flag.

Assisted-by: Claude Code (Sonnet 4.5)
Signed-off-by: Wei Shi <[email protected]>

Author: shi2wei3

crates/lib/src/cli.rs

@@ -108,6 +108,14 @@ pub(crate) struct UpgradeOpts {
     #[clap(long, conflicts_with_all = ["check", "apply"])]
     pub(crate) download_only: bool,
 
+    /// Apply a staged deployment that was previously downloaded with --download-only.
+    ///
+    /// This unlocks the staged deployment without checking for newer updates from the registry.
+    /// The deployment will be applied on the next shutdown or reboot. Use with --apply to
+    /// reboot immediately.
+    #[clap(long, conflicts_with_all = ["check", "download_only"])]
+    pub(crate) apply_staged: bool,
+
     #[clap(flatten)]
     pub(crate) progress: ProgressOptions,
 }
@@ -933,6 +941,30 @@ async fn upgrade(
     let staged = host.status.staged.as_ref();
     let staged_image = staged.as_ref().and_then(|s| s.image.as_ref());
     let mut changed = false;
+
+    // Handle --apply-staged: unlock existing staged deployment without registry check
+    if opts.apply_staged {
+        let staged_deployment = storage
+            .get_ostree()?
+            .staged_deployment()
+            .ok_or_else(|| anyhow::anyhow!("No staged deployment found"))?;
+
+        if staged_deployment.is_finalization_locked() {
+            storage
+                .get_ostree()?
+                .change_finalization(&staged_deployment)?;
+            println!("Staged deployment will now be applied on reboot");
+        } else {
+            println!("Staged deployment is already set to apply on reboot");
+        }
+
+        handle_staged_soft_reboot(booted_ostree, opts.soft_reboot, &host)?;
+        if opts.apply {
+            crate::reboot::reboot()?;
+        }
+        return Ok(());
+    }
+
     if opts.check {
         let imgref = imgref.clone().into();
         let mut imp = crate::deploy::new_importer(repo, &imgref).await?;

docs/src/upgrades.md

@@ -40,24 +40,36 @@ In the output, you'll see `Download-only: yes` for deployments in download-only
 
 #### Applying download-only updates
 
-There are two ways to apply a staged update that is in download-only mode:
+There are three ways to apply a staged update that is in download-only mode:
 
-**Option 1: Apply immediately with reboot**
+**Option 1: Apply the staged update without checking for newer updates**
 
 ```shell
-bootc upgrade --apply
+bootc upgrade --apply-staged
 ```
 
-This will clear the download-only flag and immediately reboot into the staged deployment.
+This unlocks the staged deployment for automatic application on the next shutdown or reboot,
+without checking the registry for newer updates. This is useful when you want to apply the
+already-downloaded update at a scheduled time.
 
-**Option 2: Clear download-only for automatic application**
+**Option 2: Apply the staged update and reboot immediately**
+
+```shell
+bootc upgrade --apply-staged --apply
+```
+
+This unlocks the staged deployment and immediately reboots into it, without checking for
+newer updates.
+
+**Option 3: Check for newer updates and apply**
 
 ```shell
 bootc upgrade
 ```
 
-Running `bootc upgrade` without flags on a staged deployment in download-only mode will
-clear the flag. The deployment will then be applied automatically on the next shutdown or reboot.
+Running `bootc upgrade` without flags will check the registry for updates. If the staged
+deployment matches the latest available update, it will be unlocked. If a newer update is
+available, the staged deployment will be replaced with the newer version.
 
 #### Checking for updates without side effects
 
@@ -84,15 +96,23 @@ bootc status --verbose
 # 3. Test or wait for maintenance window...
 
 # 4. Apply the update (choose one):
-# Option A: Clear download-only flag and let it apply on next shutdown
-bootc upgrade
+# Option A: Apply staged update without registry check
+bootc upgrade --apply-staged
+
+# Option B: Apply staged update and reboot immediately (no registry check)
+bootc upgrade --apply-staged --apply
 
-# Option B: Apply immediately with reboot
-bootc upgrade --apply
+# Option C: Check for newer updates first, then apply
+bootc upgrade
 ```
 
 **Important notes**:
 
+- **Registry check difference**: `bootc upgrade --apply-staged` does NOT check the registry for
+  newer updates, while `bootc upgrade` always checks. Use `--apply-staged` when you want to
+  apply the specific version you already downloaded, regardless of whether newer updates are
+  available.
+
 - If you reboot before applying a download-only update, the system will boot into the
   current deployment and the staged deployment will be discarded. However, the downloaded image
   data remains cached, so re-running `bootc upgrade --download-only` will be fast and won't

tmt/tests/booted/test-25-download-only-upgrade.nu

@@ -13,7 +13,7 @@
 # reboot (should still boot into v1, staged deployment discarded)
 # verify staged deployment is null (discarded on reboot)
 # bootc upgrade --download-only (re-stage v2 in download-only mode)
-# bootc upgrade (clear download-only mode)
+# bootc upgrade --apply-staged (clear download-only mode without registry check)
 # reboot (should boot into v2)
 #
 use std assert
@@ -113,9 +113,9 @@ def third_boot [] {
     assert ($status_json.status.staged != null) "Staged deployment should exist"
     assert ($status_json.status.staged.downloadOnly) "Staged deployment should be in download-only mode"
 
-    # Now clear download-only mode by running upgrade without flags
-    print "Clearing download-only mode with bootc upgrade"
-    bootc upgrade
+    # Now clear download-only mode by running upgrade --apply-staged (without registry check)
+    print "Clearing download-only mode with bootc upgrade --apply-staged"
+    bootc upgrade --apply-staged
 
     # Verify via JSON that deployment is not in download-only mode
     let status_after_json = bootc status --json | from json