DeployCloudScpModule Migration Guide

Overview

DeployCloudScpModule is a retired compatibility shell. Version 1.0 ran ssh and scp directly from the workflow worker, disabled SSH host-key verification, wrote private keys to undeleted temporary files, accepted caller-controlled shell commands and paths, and performed elevated remote mutations while exposing no Workflow Studio inputs or outputs.

Version 2.0 keeps the Java class and Spring bean loadable so saved workflows can be inspected and migrated, but hides the module from new Workflow Studio catalogs. Execution now fails closed with MODULE_RETIRED, performs no credential, network, process, or remote-filesystem work, and returns DeploymentRunnerModule as the governed migration target.

DeploymentRunnerModule delegates an approved fixed profile to a node-local runner. It requires an immutable artifact reference and SHA-256, a bounded release reference and idempotency key, an installed deployment profile, and the platform's deployment approval capability.

Usage

1. Find saved workflow tasks whose module type is DeployCloudScpModule.
2. Reconcile the last verified release and remote state. A legacy SUCCESS status is not proof of host-key verification, backup integrity, restart success, or health-check authenticity.
3. Publish the artifact through the canonical workflow artifact store and record its immutable workflow-artifact: reference and lowercase SHA-256.
4. Ask an operator to install or approve a node-local deployment profile. Do not copy SSH keys, passwords, shell commands, hostnames, or arbitrary paths into workflow inputs.
5. Replace the legacy task with DeploymentRunnerModule, select production.deploy or production.rollback, and bind the approved profile.
6. Test the profile in its authorized environment and reconcile the runner receipt before production activation.

Inputs

The retired module ignores all legacy inputs. It never opens the artifact, resolves the host, reads a key, executes a command, or contacts a health endpoint.

The replacement runner accepts:

Name	Type	Required	Description
artifactRef	string	yes	Immutable workflow-artifact: reference.
artifactSha256	string	yes	Expected 64-character lowercase SHA-256.
releaseRef	string	yes	Bounded release identifier.
idempotencyKey	string	yes	Logical deployment key used by the runner for reconciliation.
context	object	no	Authorized, non-secret deployment context.

Outputs

The compatibility shell always returns:

Name	Type	Description
status	string	Always error.
error	object	Safe MODULE_RETIRED, retryable:false, and migration guidance.

DeploymentRunnerModule returns status, operation, deploymentProfile, and a sanitized runner result after a successful bounded response.

IntegrationAccount Requirements

DeployCloudScpModule never resolves or uses an IntegrationAccount. Remove any account, raw password, or key associated with the legacy task.

DeploymentRunnerModule does not accept workflow-provided SSH credentials. When a runner credential is required, the node configuration must use a secure credential reference resolved by WorkflowNodeCredentialBroker. The deployment profile owns host verification, least-privilege credentials, destination paths, backup policy, restart behavior, and health checks outside the workflow payload.

Configuration

The retired module has no active configuration. Saved host, port, username, auth, remote_path, artifact, post_deploy, timeout, backup, and routing fields are ignored.

Configure the replacement with immutable values:

{
  "operation": "production.deploy",
  "deploymentProfile": "valkyrai-docs-production",
  "timeoutMs": 300000
}

The runner endpoint is fixed by node configuration to the exact loopback execution route; workflows cannot supply or redirect it.

Operations

DeployCloudScpModule supports only one compatibility operation: reject execution and identify the migration target. It does not connect, upload, back up, change permissions, restart services, verify HTTP endpoints, retry, or roll back.

DeploymentRunnerModule supports only production.deploy and production.rollback. The selected installed profile defines the exact allowed destination and commands. The workflow supplies immutable artifact and release identity, not shell syntax.

Errors and Failure Modes

Failure	Behavior	Recovery
Any legacy execution	Returns MODULE_RETIRED with retryable:false.	Replace the task; retrying cannot re-enable SCP.
Legacy task contains a key or password	The value is ignored and never emitted.	Remove it and rotate it if version 1.0 could have materialized it locally.
Legacy deployment disabled host-key checks	Treat the destination identity as unverified.	Reconcile the host through the approved profile before another deployment.
Runner profile is missing	Replacement execution fails before deployment.	Install and authorize the exact node-local profile.
Runner response is ambiguous	Do not blindly replay.	Reconcile the runner receipt using the release and idempotency keys.
Artifact hash differs	Runner must reject the deployment.	Rebuild or republish the immutable artifact and update the expected hash deliberately.

Example

A saved legacy task reaches the compatibility shell:

{
  "host": "prod.example.internal",
  "artifact": "/workspace/app.jar",
  "remote_path": "/opt/app/app.jar"
}

Expected result:

{
  "status": "error",
  "error": {
    "code": "MODULE_RETIRED",
    "message": "DeployCloudScpModule is retired; use an approved DeploymentRunnerModule profile",
    "retryable": false,
    "migrationTargets": ["DeploymentRunnerModule"]
  }
}

Notes

• Pagination: neither the retired shell nor the deployment runner paginates.
• Limits: the shell returns immediately. The runner bounds request and response sizes and allows a 1-second to 15-minute configured timeout.
• Idempotency: the compatibility response is deterministic and side-effect free. The old hash marker could report success without proving remote state. The runner requires a caller idempotency key and external receipt reconciliation.
• API constraints: the runner endpoint is the exact node-local loopback route. Workflow inputs cannot change its scheme, host, path, query, or fragment.
• SSH trust: the retired module no longer alters StrictHostKeyChecking or UserKnownHostsFile. Host identity belongs to the approved profile and must not be weakened by a workflow.
• Destructive behavior: the compatibility shell performs none. Runner deploy and rollback operations are approval-gated irreversible writes and must remain scoped to installed profiles.
• Runtime deployment: source, tests, and documentation can be merged and published independently, but live Workflow Studio will continue to show version 1.0 until a normal backend deployment includes version 2.0.
• Unverified boundary: deterministic tests prove fail-closed output, secret non-disclosure, repeatability, metadata discovery exclusion, and direct compatibility lookup. No SSH provider test is needed because the retired module intentionally performs no provider behavior.