Skip to content

feat(cli): add cdk deploy --method=execute-change-set for two-step deployment workflows#1271

Draft
mrgrain wants to merge 3 commits intomainfrom
mrgrain/feat/deploy/execute-change-set-method
Draft

feat(cli): add cdk deploy --method=execute-change-set for two-step deployment workflows#1271
mrgrain wants to merge 3 commits intomainfrom
mrgrain/feat/deploy/execute-change-set-method

Conversation

@mrgrain
Copy link
Copy Markdown
Contributor

@mrgrain mrgrain commented Mar 27, 2026

Fixes #801

This adds a new --method=execute-change-set option to cdk deploy that enables a two-step deployment workflow where users first create a change set for review, then explicitly execute it after inspection.

The motivation comes from users who want to verify exactly what CloudFormation will do before committing to a deployment. While cdk diff infers changes from templates, an actual change set created by CloudFormation is the source of truth for what will happen. This is especially important for stateful resources where accidental replacements can cause data loss.

The intended workflow is:

cdk deploy MyStack --method=prepare-change-set --change-set-name MyChangeSet
# review the change set in the AWS Console or via AWS CLI
cdk deploy MyStack --method=execute-change-set --change-set-name MyChangeSet --require-approval=any-change

The execute-change-set method bypasses synthesis and stack selection entirely since the change set already exists in CloudFormation. In the CLI, this short-circuits directly to toolkit-lib rather than adding a new branch to CdkToolkit, keeping the existing deploy flow untouched. The method requires --change-set-name and exactly one stack name. Options that only apply during change set creation (like --force, --parameters, --no-rollback, --import-existing-resources, --revert-drift) are ignored with a warning when used with this method.

On the toolkit-lib side, a new ExecuteChangeSetDeployment type is added to the DeploymentMethod union, and a new Toolkit.executeChangeSet() method handles the execution by working directly with CloudFormation APIs without requiring a cloud assembly.

Checklist

  • This change contains a major version upgrade for a dependency and I confirm all breaking changes are addressed
    • Release notes for the new version:

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

@mrgrain mrgrain marked this pull request as draft March 27, 2026 14:02
@aws-cdk-automation aws-cdk-automation requested a review from a team March 27, 2026 14:02
@mrgrain mrgrain force-pushed the mrgrain/feat/deploy/execute-change-set-method branch from 82a7fbd to 309f84e Compare March 27, 2026 15:02
@codecov-commenter
Copy link
Copy Markdown

codecov-commenter commented Mar 27, 2026

Codecov Report

❌ Patch coverage is 45.23810% with 23 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.96%. Comparing base (718f28c) to head (dc552f8).

Files with missing lines Patch % Lines
packages/aws-cdk/lib/cli/cdk-toolkit.ts 11.53% 23 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #1271      +/-   ##
==========================================
- Coverage   88.11%   87.96%   -0.15%     
==========================================
  Files          73       73              
  Lines       10359    10398      +39     
  Branches     1410     1421      +11     
==========================================
+ Hits         9128     9147      +19     
- Misses       1204     1223      +19     
- Partials       27       28       +1     
Flag Coverage Δ
suite.unit 87.96% <45.23%> (-0.15%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

…ts\n\nInstead of short-circuiting in cli.ts, the execute-change-set method\nnow flows through the normal deploy path:\n\n- cli.ts -> CdkToolkit.deploy() -> Toolkit.executeChangeSet()\n- Toolkit.deploy() intercepts execute-change-set before synth\n- CdkToolkit.deploy() intercepts before stack selection\n- determineDeploymentMethod() handles validation and returns the type\n- deployStack guard updated to indicate a bug, not user error
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

(deploy): Manual changeset approval via CLI

3 participants