For Technical Users

Technical Overview

NDploy is a deterministic CLI for promoting n8n workflows from DEV to PROD with dependency awareness and controlled execution. This documentation explains technical behavior from an operator perspective, focusing on guarantees, boundaries, and runtime decisions.

Core Model

Create phase: initializes a project from a DEV workflow id and stores root workflow metadata.
Plan phase: discovers dependencies and builds plan artifacts inside the project.
Apply phase: validates plan freshness, executes actions in dependency order, and writes runtime results.
Publish phase: explicitly activates workflows after verification.

What NDploy Is Optimized For

Consistent DEV to PROD promotion for workflows with sub-workflows, credentials, and data tables.
Safe, reviewable changes with a file artifact before execution.
Idempotent behavior where possible, including update skipping for equivalent PROD content.

Conceptual Guarantees

Area	Guarantee	Limit
Dependency Discovery	Recursively includes workflow dependencies required by the root workflow.	References outside the analyzed graph are not rewritten unless resolvable in mapping.
Credential Handling	Credentials are handled through source/target snapshots plus an editable `credentials_manifest.json`.	Operators still review and validate template data before apply.
Idempotence	Equivalent workflow updates can be skipped.	Equivalence is structural; external system state is out of scope.
Safety	Root workflow is not auto-published by apply.	Operator still decides final activation timing.

Recommended Operational Sequence

Init project: ndeploy init <workflow_id_dev> [project_root]
Generate plan: ndeploy plan <project>
Review reports/plan_summary.json (plus plan.json if needed).
Run ndeploy credentials fetch <project>, then credentials compare, then credentials merge-missing.
Review credentials_manifest.json and run ndeploy credentials validate <project> --side manifest --strict before apply.
Apply plan: ndeploy apply <project>
Review reports/deploy_summary.json (and reports/deploy_result.json if needed).
Publish root workflow manually when release criteria are met.

Contract: plan is a point-in-time artifact; apply is the runtime source of truth.