cpflow 5.1.1 → 5.3.0

data/lib/command/apply_template.rb

@@ -9,7 +9,8 @@ module Command
       app_option(required: true),
       location_option,
       skip_confirm_option,
-      add_app_identity_option
+      add_app_identity_option,
+      preserve_existing_runtime_option
     ].freeze
     DESCRIPTION = "Applies application-specific configs from templates"
     LONG_DESCRIPTION = <<~DESC
@@ -17,6 +18,8 @@ module Command
       - Publishes (creates or updates) those at Control Plane infrastructure
       - Picks templates from the `.controlplane/templates` directory
       - Templates are ordinary Control Plane templates but with variable preprocessing
+      - Use `--preserve-existing-runtime` to retain each workload container's configured app image, even when the workload is unready, and skip existing secret resources entirely while applying other template changes
+      - Missing or invalid workload images use only an unambiguous app image from ready workloads; refresh fails before applying templates when no safe fallback exists
 
       **Preprocessed template variables:**
 
@@ -58,6 +61,7 @@ module Command
       @skipped_templates = []
 
       templates = @template_parser.parse(@names_to_filenames.values)
+      templates = preserve_existing_runtime(templates) if config.options[:preserve_existing_runtime]
       pending_templates = confirm_templates(templates)
       add_app_identity_template(pending_templates) if config.options[:add_app_identity]
       pending_templates.each do |template|
@@ -117,7 +121,7 @@ module Command
     end
 
     def confirm_workload(template) # rubocop:disable Naming/PredicateMethod
-      workload = cp.fetch_workload(template["name"])
+      workload = fetch_workload(template["name"])
       return true unless workload
 
       confirmed = confirm_apply("Workload '#{template['name']}' already exists, do you want to re-create it?")
@@ -146,6 +150,104 @@ module Command
       pending_templates
     end
 
+    def preserve_existing_runtime(templates)
+      cache_existing_workloads(templates)
+      ready_fallback_image = unambiguous_ready_app_image
+
+      templates.filter_map do |template|
+        if template["kind"] == "secret" && cp.fetch_secret(template["name"])
+          report_skipped(template)
+          next
+        end
+
+        preserve_workload_images(template, ready_fallback_image) if template["kind"] == "workload"
+        template
+      end
+    end
+
+    def cache_existing_workloads(templates)
+      template_names = templates.filter_map { |template| template["name"] if template["kind"] == "workload" }
+      workloads = cp.fetch_workloads
+      cp.fetch_gvc! unless workloads
+      @existing_workloads = Array(workloads.fetch("items")).to_h do |workload|
+        [workload.fetch("name"), workload]
+      end
+      template_names.each { |name| @existing_workloads[name] = nil unless @existing_workloads.key?(name) }
+    end
+
+    def fetch_workload(name)
+      return @existing_workloads[name] if @existing_workloads&.key?(name)
+
+      cp.fetch_workload(name)
+    end
+
+    def unambiguous_ready_app_image
+      app_images = ready_existing_app_workloads.flat_map do |workload|
+        Array(workload.dig("spec", "containers")).filter_map do |container|
+          container["image"] if deployable_app_image?(container["image"])
+        end
+      end
+      image_prefix = "/org/#{config.org}/image/"
+      canonical_images = app_images.map { |image| image.delete_prefix(image_prefix) }
+      app_images.first if canonical_images.uniq.one?
+    end
+
+    def ready_existing_app_workloads
+      @existing_workloads.values.compact.filter_map do |workload|
+        next unless Array(workload.dig("spec", "containers")).any? do |container|
+          deployable_app_image?(container["image"])
+        end
+
+        workload = workload_with_readiness(workload)
+        workload if workload_ready?(workload)
+      end
+    end
+
+    def preserve_workload_images(template, ready_fallback_image) # rubocop:disable Metrics/MethodLength
+      existing_workload = fetch_workload(template["name"])
+      existing_containers = Array(existing_workload&.dig("spec", "containers"))
+                            .to_h { |container| [container["name"], container] }
+
+      Array(template.dig("spec", "containers")).each do |container|
+        next unless app_image?(container["image"])
+
+        existing_image = existing_containers.dig(container["name"], "image")
+        preserved_image = preserved_image(existing_image, ready_fallback_image)
+        unless preserved_image
+          raise "Cannot safely refresh app image for workload '#{template['name']}' " \
+                "without a valid existing workload image or an unambiguous ready fallback image."
+        end
+
+        container["image"] = preserved_image
+      end
+    end
+
+    def preserved_image(existing_image, ready_fallback_image)
+      return existing_image if deployable_app_image?(existing_image)
+
+      ready_fallback_image
+    end
+
+    def workload_ready?(workload)
+      workload&.dig("status", "readyLatest") == true
+    end
+
+    def workload_with_readiness(workload)
+      return workload unless workload.dig("status", "readyLatest").nil?
+
+      cp.fetch_workload_with_status(workload.fetch("name")) || workload
+    end
+
+    def app_image?(image)
+      image.to_s.match?(
+        %r{\A(?:/org/#{Regexp.escape(config.org)}/image/)?#{Regexp.escape(config.app)}[:@]}
+      )
+    end
+
+    def deployable_app_image?(image)
+      app_image?(image) && !image.to_s.end_with?(Controlplane::NO_IMAGE_AVAILABLE)
+    end
+
     def add_app_identity_template(templates)
       app_template_index = templates.index { |template| template["name"] == config.app }
       app_identity_template_index = templates.index { |template| template["name"] == config.identity }

data/lib/command/base.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "shellwords"
 require_relative "../core/helpers"
 
 module Command
@@ -11,6 +12,7 @@ module Command
     VALIDATIONS_WITHOUT_ADDITIONAL_OPTIONS = %w[config].freeze
     VALIDATIONS_WITH_ADDITIONAL_OPTIONS = %w[templates].freeze
     ALL_VALIDATIONS = VALIDATIONS_WITHOUT_ADDITIONAL_OPTIONS + VALIDATIONS_WITH_ADDITIONAL_OPTIONS
+    GENERATED_POSTGRES_PASSWORD_PLACEHOLDER = "the_password"
 
     # Used to call the command (`cpflow SUBCOMMAND_NAME NAME`)
     SUBCOMMAND_NAME = nil
@@ -49,7 +51,7 @@ module Command
 
     def self.all_commands # rubocop:disable Metrics/MethodLength
       Dir["#{__dir__}/**/*.rb"].each_with_object({}) do |file, result|
-        content = File.read(file)
+        content = File.read(file, encoding: "UTF-8")
 
         classname = content.match(/^\s+class (?!Base\b)(\w+) < (?:.*(?!Command::)Base)(?:$| .*$)/)&.captures&.first
         next unless classname
@@ -96,7 +98,7 @@ module Command
       }
     end
 
-    def self.workload_option(required: false)
+    def self.workload_option(required: false, repeatable: false)
       {
         name: :workload,
         params: {
@@ -104,6 +106,7 @@ module Command
           banner: "WORKLOAD_NAME",
           desc: "Workload name",
           type: :string,
+          repeatable: repeatable,
           required: required
         }
       }
@@ -458,6 +461,28 @@ module Command
       }
     end
 
+    def self.refresh_templates_option(required: false)
+      {
+        name: :refresh_templates,
+        params: {
+          desc: "Refreshes configured templates for an existing app without running post-creation hooks",
+          type: :boolean,
+          required: required
+        }
+      }
+    end
+
+    def self.preserve_existing_runtime_option(required: false)
+      {
+        name: :preserve_existing_runtime,
+        params: {
+          desc: "Preserves deployed app images and skips existing secret resources entirely while applying templates",
+          type: :boolean,
+          required: required
+        }
+      }
+    end
+
     def self.skip_pre_deletion_hook_option(required: false)
       {
         name: :skip_pre_deletion_hook,
@@ -527,10 +552,12 @@ module Command
       end
     end
 
-    # NOTE: use simplified variant atm, as shelljoin do different escaping
-    # TODO: most probably need better logic for escaping various quotes
     def args_join(args)
-      args.join(" ")
+      # A single CLI argument is an intentional shell program (for example, an env assignment or pipeline).
+      # Multiple CLI arguments are argv elements and must be escaped before entering the remote shell script.
+      return args.first if args.size == 1
+
+      Shellwords.join(args)
     end
 
     def progress
@@ -583,6 +610,20 @@ module Command
       success
     end
 
+    def wait_for_workloads_ready(workloads, reverse: false)
+      workloads_to_wait_for = reverse ? workloads.reverse : workloads
+
+      workloads_to_wait_for.each do |workload|
+        if cp.workload_suspended?(workload)
+          progress.puts("Workload '#{workload}' is suspended. Skipping...")
+        else
+          step("Waiting for workload '#{workload}' to be ready", retry_on_failure: true) do
+            cp.workload_deployments_ready?(workload, location: config.location, expected_status: true)
+          end
+        end
+      end
+    end
+
     def cp
       @cp ||= Controlplane.new(config)
     end
@@ -604,9 +645,32 @@ module Command
       raise shared_secret_policy_missing_message(grant) if policy.nil?
 
       ensure_shared_secret_policy_targets_secret!(grant, policy)
+      warn_if_shared_secret_uses_generated_password_placeholder(grant)
       policy
     end
 
+    def warn_if_shared_secret_uses_generated_password_placeholder(grant)
+      secret_name = grant.fetch(:secret_name)
+      secret = cp.reveal_secret(secret_name)
+      return unless secret&.dig("data", "password") == GENERATED_POSTGRES_PASSWORD_PLACEHOLDER
+
+      Shell.warn(
+        "Shared secret grant '#{grant.fetch(:name)}' targets secret '#{secret_name}', whose password " \
+        "is still the generated placeholder. Review apps will fail authentication until it is replaced."
+      )
+    # This is a best-effort warning. API, transport, and response-shape failures
+    # must not turn an optional diagnostic into a deployment blocker.
+    rescue StandardError
+      debug_shared_secret_placeholder_check_failure(secret_name)
+    end
+
+    def debug_shared_secret_placeholder_check_failure(secret_name)
+      Shell.debug(
+        "WARN",
+        "Could not inspect shared secret '#{secret_name}'; continuing without the optional placeholder diagnostic."
+      )
+    end
+
     def bind_shared_secret_policy_grant(grant, policy)
       policy_name = grant.fetch(:policy_name)
       return if identity_bound_to_policy_with_reveal?(policy)

data/lib/command/deploy_image.rb

@@ -3,53 +3,129 @@
 require "resolv"
 
 module Command
-  class DeployImage < Base
+  class DeployImage < Base # rubocop:disable Metrics/ClassLength
     NAME = "deploy-image"
     OPTIONS = [
       app_option(required: true),
+      workload_option(repeatable: true),
       run_release_phase_option,
       use_digest_image_ref_option
     ].freeze
     DESCRIPTION = "Deploys the latest image to app workloads, and runs a release script (optional)"
     LONG_DESCRIPTION = <<~DESC
       - Deploys the latest image to app workloads
+      - Use `--workload`/`-w` one or more times to deploy only selected app workloads
+      - If `deploy_order` is configured and no `--workload` is provided, deploys ordered workload groups one at a time and waits for each group to be ready before continuing
+      - Workloads listed in `app_workloads` but omitted from `deploy_order` deploy last as an implicit final group
       - Runs a release script before deploying if `release_script` is specified in the `.controlplane/controlplane.yml` file and `--run-release-phase` is provided
       - The release script is run in the context of `cpflow run` with the latest image
       - If the release script exits with a non-zero code, the command will stop executing and also exit with a non-zero code
       - If `use_digest_image_ref` is `true` in the `.controlplane/controlplane.yml` file or `--use-digest-image-ref` option is provided, deployed image's reference will include its digest
       - Repairs missing `shared_secret_grants` policy bindings before running a release phase or updating workloads
     DESC
+    EXAMPLES = <<~EX
+      ```sh
+      # Deploys the latest image to all app workloads.
+      cpflow deploy-image -a $APP_NAME
+
+      # Deploys only one app workload.
+      cpflow deploy-image -a $APP_NAME -w node-renderer
+
+      # Deploys only selected app workloads.
+      cpflow deploy-image -a $APP_NAME -w node-renderer -w sidekiq
+      ```
+    EX
 
     def call
       release_script = release_script_to_run
       image = resolve_image_to_deploy
       shared_secret_policy_grant_pairs = resolve_shared_secret_policy_grants
-      workload_data_by_name = app_workload_data
+      workload_data_by_name = app_workload_data(workload_names_to_deploy)
 
       bind_shared_secret_policy_grants(shared_secret_policy_grant_pairs)
       run_release_script(release_script) if release_script
-      deploy_image_to_workloads(image, workload_data_by_name)
+      deploy_image(image, workload_data_by_name)
     end
 
     private
 
-    def app_workload_data
-      config[:app_workloads].to_h do |workload|
+    def workload_names_to_deploy
+      app_workloads = config[:app_workloads]
+      requested_workloads = requested_workload_names
+      return app_workloads if requested_workloads.empty?
+
+      ensure_workloads_configured!(requested_workloads, app_workloads)
+      requested_workloads
+    end
+
+    def ensure_workloads_configured!(requested_workloads, app_workloads)
+      requested_workloads.each do |workload|
+        next if app_workloads.include?(workload)
+
+        raise "Workload '#{workload}' must be listed in app_workloads for app '#{config.app}'."
+      end
+    end
+
+    def app_workload_data(workloads)
+      workloads.to_h do |workload|
         [workload, cp.fetch_workload!(workload)]
       end
     end
 
+    def deploy_image(image, workload_data_by_name)
+      deployed_endpoints = {}
+
+      if deploy_in_order?
+        deploy_image_to_ordered_workloads(image, workload_data_by_name, deployed_endpoints)
+      else
+        deployed_endpoints.merge!(deploy_image_to_workloads(image, workload_data_by_name))
+      end
+    ensure
+      print_deployed_endpoints(deployed_endpoints)
+    end
+
+    def deploy_in_order?
+      requested_workload_names.empty? && config.deploy_order
+    end
+
+    def deployment_groups(workload_data_by_name)
+      ordered_groups = config.deploy_order
+      ordered_workloads = ordered_groups.flatten
+      unordered_workloads = workload_data_by_name.keys - ordered_workloads
+
+      [*ordered_groups, unordered_workloads].reject(&:empty?)
+    end
+
+    def deploy_image_to_ordered_workloads(image, workload_data_by_name, deployed_endpoints)
+      deployment_groups(workload_data_by_name).each do |group|
+        deployed_endpoints.merge!(deploy_image_to_workloads(image, workload_data_by_name.slice(*group)))
+        wait_for_workloads_ready(group)
+      end
+    end
+
+    def requested_workload_names
+      @requested_workload_names ||= Array(config.options[:workload]).map(&:to_s).uniq
+    end
+
+    def app_image?(image)
+      image.to_s.match?(
+        %r{\A(?:/org/#{Regexp.escape(config.org)}/image/)?#{Regexp.escape(config.app)}[:@]}
+      )
+    end
+
     def deploy_image_to_workloads(image, workload_data_by_name) # rubocop:disable Metrics/MethodLength
       deployed_endpoints = {}
 
       workload_data_by_name.each do |workload, workload_data|
         workload_data.dig("spec", "containers").each do |container|
-          next unless container["image"].match?(%r{^/org/#{config.org}/image/#{config.app}[:@]})
+          next unless app_image?(container["image"])
 
           container_name = container["name"]
           step("Deploying image '#{image}' for workload '#{workload}'") do
             cp.workload_set_image_ref(workload, container: container_name, image: image)
             deployed_endpoints[workload] = endpoint_for_workload(workload_data)
+            # A missing public endpoint is valid; the image update still completed successfully.
+            true
           end
           # Deploy the first matching app-image container per workload; CPLN workloads
           # are expected to have a single container that runs the app image.
@@ -57,9 +133,13 @@ module Command
         end
       end
 
+      deployed_endpoints
+    end
+
+    def print_deployed_endpoints(deployed_endpoints)
       progress.puts("\nDeployed endpoints:")
       deployed_endpoints.each do |workload, endpoint|
-        progress.puts("  - #{workload}: #{endpoint}")
+        progress.puts("  - #{workload}: #{endpoint || '(no public endpoint)'}")
       end
     end
 
@@ -100,9 +180,15 @@ module Command
 
     def endpoint_for_workload(workload_data)
       endpoint = workload_data.dig("status", "endpoint")
+      return fallback_endpoint_for_workload(workload_data) unless endpoint
+
       Resolv.getaddress(endpoint.split("/").last)
       endpoint
     rescue Resolv::ResolvError
+      fallback_endpoint_for_workload(workload_data)
+    end
+
+    def fallback_endpoint_for_workload(workload_data)
       deployments = cp.fetch_workload_deployments(workload_data["name"])
       deployments.dig("items", 0, "status", "endpoint")
     end

data/lib/command/promote_app_from_upstream.rb

@@ -14,6 +14,7 @@ module Command
       - It performs the following steps:
         - Runs `cpflow copy-image-from-upstream` to copy the latest image from upstream
         - Runs `cpflow deploy-image` to deploy the image
+        - Honors `deploy_order` from `.controlplane/controlplane.yml` through `cpflow deploy-image`
         - If `.controlplane/controlplane.yml` includes the `release_script`, `cpflow deploy-image` will use the `--run-release-phase` option
         - If the release script exits with a non-zero code, the command will stop executing and also exit with a non-zero code
         - If `use_digest_image_ref` is `true` in the `.controlplane/controlplane.yml` file or `--use-digest-image-ref` option is provided, deployed image's reference will include its digest

data/lib/command/ps_wait.rb

@@ -26,19 +26,11 @@ module Command
       ```
     EX
 
-    def call # rubocop:disable Metrics/MethodLength
+    def call
       @workloads = [config.options[:workload]] if config.options[:workload]
       @workloads ||= config[:app_workloads] + config[:additional_workloads]
 
-      @workloads.reverse_each do |workload|
-        if cp.workload_suspended?(workload)
-          progress.puts("Workload '#{workload}' is suspended. Skipping...")
-        else
-          step("Waiting for workload '#{workload}' to be ready", retry_on_failure: true) do
-            cp.workload_deployments_ready?(workload, location: config.location, expected_status: true)
-          end
-        end
-      end
+      wait_for_workloads_ready(@workloads, reverse: true)
     end
   end
 end

data/lib/command/run.rb

@@ -47,8 +47,21 @@ module Command
         and also overridden per job through `--cpu` and `--memory`)
       - By default, the job is stopped if it takes longer than 6 hours to finish
         (can be configured though `runner_job_timeout` in `controlplane.yml`)
+      - Waiting for a runner replica is limited to the smaller of `runner_job_timeout` and 1000 seconds.
+        A terminal cron status fails immediately, and reaching the observation deadline reports the last safe status
       - Non-interactive jobs return the Control Plane cron job status even when the job finishes before
         Control Plane exposes a runner replica to attach logs to
+      - Injects `CPFLOW_GVC_ID` and `CPFLOW_GVC_CREATED` into the job, exposing the app's immutable GVC
+        identity, so that a command such as a release script can tell which GVC incarnation it is running in.
+        These change when a GVC is deleted and recreated under the same name, and only then, unlike
+        `CPLN_GVC_ALIAS`, which is also embedded in mutable derived values such as the app domain and so
+        cannot be attributed to recreation alone
+      - `CPFLOW_GVC_CREATED` is the GVC's creation timestamp as returned by the Control Plane API and passed
+        through unmodified, currently an ISO 8601 UTC timestamp with millisecond precision and a `Z` suffix
+        (e.g. `2026-08-28T00:54:48.648Z`)
+      - Both variables are always set, and are empty when the GVC cannot be read, so that a consumer can
+        fail closed. They are never omitted, because the runner inherits the original workload's
+        environment and an omitted variable could otherwise expose a stale inherited value
     DESC
     EXAMPLES = <<~EX.freeze
       ```sh
@@ -69,7 +82,8 @@ module Command
       # - stop the job
       cpflow run -a $APP_NAME --detached -- rails db:migrate
 
-      # The command needs to be quoted if setting an env variable or passing args.
+      # Quote the whole command to intentionally opt into shell syntax such as an env assignment.
+      # Separately supplied command arguments are passed literally.
       cpflow run -a $APP_NAME -- 'SOME_ENV_VAR=some_value rails db:migrate'
 
       # Uses a different image (which may not be promoted yet).
@@ -95,6 +109,9 @@ module Command
     DEFAULT_JOB_MEMORY = "2Gi"
     DEFAULT_JOB_TIMEOUT = 21_600 # 6 hours
     DEFAULT_JOB_HISTORY_LIMIT = 10
+    MAX_REPLICA_OBSERVATION_SECONDS = 1_000
+    REPLICA_OBSERVATION_POLL_INTERVAL_SECONDS = 1
+    NORMALIZED_JOB_STATUS_PATTERN = /\A[a-z][a-z0-9_-]{0,31}\z/
     MAGIC_END = "---cpflow run command finished---"
 
     attr_reader :interactive, :detached, :location, :original_workload, :runner_workload,
@@ -268,27 +285,80 @@ module Command
     end
 
     def wait_for_replica_for_job
-      step("Waiting for replica to start, which runs job '#{job}'", retry_on_failure: true) do
-        result = cp.fetch_workload_replicas(runner_workload, location: location)
-        @replica = result&.dig("items")&.find { |item| item.include?(job) }
+      observation_limit = [job_timeout, MAX_REPLICA_OBSERVATION_SECONDS].min
+      observation_deadline = monotonic_time + observation_limit
 
-        replica || completed_job_before_replica? || false
+      step("Waiting for runner replica to start") do
+        observe_replica_until(observation_deadline, observation_limit)
       end
     end
 
-    def completed_job_before_replica?
-      case current_job_status
+    def observe_replica_until(observation_deadline, observation_limit)
+      last_status = nil
+
+      loop do
+        ensure_before_replica_observation_deadline!(observation_deadline, observation_limit, last_status)
+
+        @replica = replica_for_job
+        return replica if replica
+
+        ensure_before_replica_observation_deadline!(observation_deadline, observation_limit, last_status)
+
+        last_status = current_job_status
+        return true if completed_job_before_replica?(last_status)
+
+        sleep_before_replica_observation_retry(observation_deadline, observation_limit, last_status)
+      end
+    end
+
+    def ensure_before_replica_observation_deadline!(observation_deadline, observation_limit, status)
+      return if monotonic_time < observation_deadline
+
+      raise replica_observation_timeout_message(observation_limit, status)
+    end
+
+    def replica_for_job
+      result = cp.fetch_workload_replicas(runner_workload, location: location)
+      result&.dig("items")&.find { |item| item.include?(job) }
+    end
+
+    def sleep_before_replica_observation_retry(observation_deadline, observation_limit, status)
+      progress.print(".")
+      remaining = observation_deadline - monotonic_time
+      raise replica_observation_timeout_message(observation_limit, status) unless remaining.positive?
+
+      Kernel.sleep([REPLICA_OBSERVATION_POLL_INTERVAL_SECONDS, remaining].min)
+    end
+
+    # Returns true for success, false while pending, and raises for a terminal non-success status.
+    def completed_job_before_replica?(status)
+      case status
       when "successful"
         @job_completed_before_replica_exit_status = ExitCode::SUCCESS
         true
       when nil, "active", "pending"
         false
       else
-        @job_completed_before_replica_exit_status = ExitCode::ERROR_DEFAULT
-        true
+        raise "Runner job ended before a replica was observed (status: #{normalized_job_status(status)})."
       end
     end
 
+    def normalized_job_status(status)
+      return "unavailable" if status.nil?
+
+      token = status.to_s.downcase
+      token.match?(NORMALIZED_JOB_STATUS_PATTERN) ? token : "unknown"
+    end
+
+    def replica_observation_timeout_message(observation_limit, status)
+      "Runner replica was not observed before the observation limit: #{format('%g', observation_limit)} seconds " \
+        "(status: #{normalized_job_status(status)})."
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
     def run_interactive
       progress.puts("Connecting to replica '#{replica}'...\n\n")
       # workload_exec returns false on non-zero exit, nil when signal-killed (e.g. Ctrl-C).
@@ -389,11 +459,12 @@ module Command
       job_start_hash["args"].push("-c")
       job_start_hash["env"] ||= []
       job_start_hash["env"].push({ "name" => "CPFLOW_RUNNER_SCRIPT", "value" => runner_script })
+      job_start_hash["env"].concat(gvc_identity_env_vars)
       if interactive
         job_start_hash["env"].push({ "name" => "CPFLOW_MONITORING_SCRIPT", "value" => interactive_monitoring_script })
 
         job_start_hash["args"].push('eval "$CPFLOW_MONITORING_SCRIPT"')
-        @command = %(bash -c 'eval "$CPFLOW_RUNNER_SCRIPT"')
+        @command = ["bash", "-c", 'eval "$CPFLOW_RUNNER_SCRIPT"']
       else
         job_start_hash["args"].push('eval "$CPFLOW_RUNNER_SCRIPT"')
       end
@@ -413,6 +484,58 @@ module Command
       job_start_hash.to_yaml
     end
 
+    # Exposes the GVC's immutable identity to the job. cpflow authenticates client-side with the
+    # operator/CI credentials, so reading the GVC here adds no GVC-view binding to the app's workload
+    # identity and leaves nothing behind for the delete lifecycle to clean up.
+    #
+    # Both variables are always emitted, empty when unknown, rather than omitted. `update_runner_workload`
+    # copies the original workload's env wholesale into the runner, so omitting them would let a value
+    # inherited from the workload survive a failed read and be mistaken for a live identity. Emitting an
+    # explicit empty value is the only way a consumer can actually fail closed.
+    def gvc_identity_env_vars
+      gvc_data = fetch_gvc_for_identity
+      gvc_id = (gvc_data && gvc_data["id"]).to_s
+      # Gated on the id so a fresh id can never be paired with an inherited timestamp.
+      gvc_created = gvc_id.empty? ? "" : gvc_data["created"].to_s
+
+      [
+        { "name" => "CPFLOW_GVC_ID", "value" => gvc_id },
+        { "name" => "CPFLOW_GVC_CREATED", "value" => gvc_created }
+      ]
+    end
+
+    # The identity is an optional enrichment, so failing to read it must never stop the job, and the
+    # variables are still emitted (empty) rather than dropped.
+    # Two reasons the rescue is deliberately broad rather than a narrow class list:
+    #
+    # 1. Availability. `cpflow run` is also the release-phase mechanism for `deploy-image`, `setup-app`,
+    #    and `delete`, so a transient error on the GVC endpoint would otherwise fail a deploy over a
+    #    variable the command does not need.
+    # 2. Taxonomy. `handle_response` raises a bare `RuntimeError` for 401 and 5xx responses, so any
+    #    "narrow" list that actually covered the real failures would have to include `RuntimeError`.
+    #
+    # `MaintenanceMode#domain_workload_update_confirmed?` rescues `StandardError` against this same API
+    # client for the same reason. The rescued body is a single external call, so a bug in this file's own
+    # logic still raises.
+    def fetch_gvc_for_identity
+      cp.fetch_gvc
+    rescue StandardError => e
+      # Deliberately `Shell.warn` rather than a `step`. `step_finish` prints a red "failed!" banner
+      # whenever its block is falsy, regardless of `abort_on_error`, so routing an optional lookup
+      # through it would show a failure on every deploy for anyone whose token omits `gvc` view -- for
+      # a read that stops nothing and leaves the exit code at 0.
+      Shell.warn(gvc_identity_error_message(e))
+      nil
+    end
+
+    # A 403 here is normally a missing `view` grant on kind `gvc`, but `ForbiddenError` renders any
+    # `/org/...` URL as "Double check your org", which sends the operator after the wrong thing.
+    def gvc_identity_error_message(error)
+      "Continuing without the GVC identity, so CPFLOW_GVC_ID and CPFLOW_GVC_CREATED are set to empty " \
+        "strings. A permission failure here usually means the token lacks `view` on kind `gvc` for this " \
+        "app, even when the message below mentions the org. #{error.message}"
+    end
+
     def interactive_monitoring_script
       <<~SCRIPT
         primary_pid=""