Runbook

Operations and Safety

This section is intended as an operator runbook for recurring releases and incident response.

Release Checklist

Create project from DEV workflow id.
Generate a fresh plan in that project.
Inspect reports/plan_summary.json.
Run ndeploy credentials fetch <project>, compare snapshots, and merge missing entries into credentials_manifest.json.
Complete or adjust required PROD credential values in each active entry's template.data.
Run ndeploy credentials validate <project> --side manifest --strict.
Apply plan with normal mode first.
Inspect reports/deploy_summary.json for executed/skipped/failed actions.
Publish root workflow explicitly when post-apply checks pass.

When to Use `--force-update`

When you explicitly want to overwrite equivalent-content protection.
When troubleshooting stale state and you need deterministic rewrite behavior.

Do not use --force-update as default. It increases write volume and can hide drift signals.

Common Warning Patterns

Warning	Impact	Action
Data table schema differs from PROD	Workflow behavior can diverge at runtime.	Validate node expectations and table access before release.
Workflow observed as different	Likely write during apply.	Review intended changes, then apply.
Workflow observed as unknown	Pre-apply prediction not reliable.	Rely on apply logs for final decision.

Troubleshooting Quick Guide

Plan validation fails in apply

This usually means DEV changed after plan generation. Regenerate plan and re-run apply.

Expected skip but got update

Compare normalized target content and check for real business-level differences like labels, filters, or settings values.

Credential-related failures after apply

Verify credentials_manifest.json contains the intended values, rerun credentials validate --side manifest --strict, and confirm whether the source/target snapshots were fetched correctly.

Command Set for Daily Ops

ndeploy init <workflow_id_dev> [project_root]
ndeploy plan <project>
ndeploy credentials fetch <project>
ndeploy credentials compare <project>
ndeploy credentials merge-missing <project>
ndeploy credentials validate <project> --side manifest --strict
ndeploy apply <project>
ndeploy info <project>
ndeploy publish <workflow_id_prod>
ndeploy orphans <project> --side target
ndeploy dangling-refs <project> --side target