upgrade: Stabilize deployment staging

We're waaay overdue for this, it's been the default
in rpm-ostree for years, and solves several important bugs
around not capturing `/etc` while things are running.

Also, `ostree admin upgrade --stage` (should) become idempotent.

Closes: https://github.com/ostreedev/ostree/issues/2389

src/libostree/ostree-sysroot-upgrader.c

@@ -646,7 +646,8 @@ ostree_sysroot_upgrader_deploy (OstreeSysrootUpgrader  *self,
   g_autoptr(OstreeDeployment) new_deployment = NULL;
 
   /* Experimental flag to enable staging */
-  if (getenv ("OSTREE_EX_STAGE_DEPLOYMENTS"))
+  gboolean stage = (self->flags & OSTREE_SYSROOT_UPGRADER_FLAGS_STAGE) > 0 || getenv ("OSTREE_EX_STAGE_DEPLOYMENTS") != NULL;
+  if (stage)
     {
       if (!ostree_sysroot_stage_tree (self->sysroot, self->osname,
                                       self->new_revision,
@@ -688,6 +689,7 @@ ostree_sysroot_upgrader_flags_get_type (void)
     {
       static const GFlagsValue values[] = {
         { OSTREE_SYSROOT_UPGRADER_FLAGS_IGNORE_UNCONFIGURED, "OSTREE_SYSROOT_UPGRADER_FLAGS_IGNORE_UNCONFIGURED", "ignore-unconfigured" },
+        { OSTREE_SYSROOT_UPGRADER_FLAGS_STAGE, "OSTREE_SYSROOT_UPGRADER_FLAGS_STAGE", "stage" },
         { 0, NULL, NULL }
       };
       GType g_define_type_id =

src/libostree/ostree-sysroot-upgrader.h

@@ -35,12 +35,15 @@ G_BEGIN_DECLS
  * OstreeSysrootUpgraderFlags:
  * @OSTREE_SYSROOT_UPGRADER_FLAGS_NONE: No options
  * @OSTREE_SYSROOT_UPGRADER_FLAGS_IGNORE_UNCONFIGURED: Do not error if the origin has an unconfigured-state key
+ * @OSTREE_SYSROOT_UPGRADER_FLAGS_STAGE: Enable "staging" (finalization at shutdown); recommended
+ *    (Since: 2021.4)
  *
  * Flags controlling operation of an #OstreeSysrootUpgrader.
  */
 typedef enum {
   OSTREE_SYSROOT_UPGRADER_FLAGS_NONE = (1 << 0),
   OSTREE_SYSROOT_UPGRADER_FLAGS_IGNORE_UNCONFIGURED = (1 << 1),
+  OSTREE_SYSROOT_UPGRADER_FLAGS_STAGE = (1 << 2),
 } OstreeSysrootUpgraderFlags;
 
 _OSTREE_PUBLIC

src/ostree/ot-admin-builtin-upgrade.c

@@ -37,6 +37,7 @@ static gboolean opt_reboot;
 static gboolean opt_allow_downgrade;
 static gboolean opt_pull_only;
 static gboolean opt_deploy_only;
+static gboolean opt_stage;
 static char *opt_osname;
 static char *opt_override_commit;
 
@@ -47,6 +48,7 @@ static GOptionEntry options[] = {
   { "override-commit", 0, 0, G_OPTION_ARG_STRING, &opt_override_commit, "Deploy CHECKSUM instead of the latest tree", "CHECKSUM" },
   { "pull-only", 0, 0, G_OPTION_ARG_NONE, &opt_pull_only, "Do not create a deployment, just download", NULL },
   { "deploy-only", 0, 0, G_OPTION_ARG_NONE, &opt_deploy_only, "Do not pull, only deploy", NULL },
+  { "stage", 0, 0, G_OPTION_ARG_NONE, &opt_stage, "Enable staging (finalization at reboot time)", NULL },
   { NULL }
 };
 
@@ -74,9 +76,13 @@ ot_admin_builtin_upgrade (int argc, char **argv, OstreeCommandInvocation *invoca
       return FALSE;
     }
 
+  OstreeSysrootUpgraderFlags flags = 0;
+  if (opt_stage)
+    flags |= OSTREE_SYSROOT_UPGRADER_FLAGS_STAGE;
+
   g_autoptr(OstreeSysrootUpgrader) upgrader =
-    ostree_sysroot_upgrader_new_for_os (sysroot, opt_osname,
-                                        cancellable, error);
+    ostree_sysroot_upgrader_new_for_os_with_flags (sysroot, opt_osname, flags,
+                                                   cancellable, error);
   if (!upgrader)
     return FALSE;