feat(deploy): add --method=execute-change-set for two-step deployment workflows\n\nAdd a new --method=execute-change-set option to cdk deploy that\nexecutes a previously created change set, bypassing synthesis and\nstack selection entirely. This enables a two-step deployment workflow:\n\n1. cdk deploy --method=prepare-change-set --change-set-name MyCS\n2. Review the change set\n3. cdk deploy MyStack --method=execute-change-set --change-set-name MyCS\n\nChanges across toolkit-lib and CLI:\n- New ExecuteChangeSetDeployment type in the DeploymentMethod union\n- New Toolkit.executeChangeSet() method that works directly with\n CloudFormation APIs without requiring a cloud assembly\n- CLI short-circuits to toolkit-lib for this method, not adding a new\n branch to CdkToolkit\n- Warns users about ignored options (--force, --parameters, etc.)\n- Requires --change-set-name and exactly one stack name

Author: mrgrain

packages/@aws-cdk-testing/cli-integ/tests/cli-integ-tests/deploy/cdk-two-step-deploy-prepare-then-execute-change-set.integtest.ts

@@ -0,0 +1,48 @@
+import { DescribeChangeSetCommand, DescribeStacksCommand } from '@aws-sdk/client-cloudformation';
+import { integTest, withDefaultFixture } from '../../../lib';
+
+integTest(
+  'two-step deploy: prepare then execute change set',
+  withDefaultFixture(async (fixture) => {
+    const changeSetName = `review-${fixture.stackNamePrefix}`;
+    const stackName = 'test-2';
+    const fullStackName = fixture.fullStackName(stackName);
+
+    // Step 1: Create the change set without executing it
+    await fixture.cdkDeploy(stackName, {
+      options: ['--method=prepare-change-set', '--change-set-name', changeSetName],
+      captureStderr: false,
+    });
+
+    // Verify the stack is in REVIEW_IN_PROGRESS
+    const describeResponse = await fixture.aws.cloudFormation.send(
+      new DescribeStacksCommand({ StackName: fullStackName }),
+    );
+    expect(describeResponse.Stacks?.[0].StackStatus).toEqual('REVIEW_IN_PROGRESS');
+
+    // Verify the change set exists and is ready
+    const changeSetResponse = await fixture.aws.cloudFormation.send(
+      new DescribeChangeSetCommand({
+        StackName: fullStackName,
+        ChangeSetName: changeSetName,
+      }),
+    );
+    expect(changeSetResponse.Status).toEqual('CREATE_COMPLETE');
+
+    // Step 2: Execute the change set
+    await fixture.cdk([
+      'deploy',
+      '--require-approval=never',
+      '--method=execute-change-set',
+      '--change-set-name', changeSetName,
+      '--progress', 'events',
+      fullStackName,
+    ]);
+
+    // Verify the stack is now deployed
+    const finalResponse = await fixture.aws.cloudFormation.send(
+      new DescribeStacksCommand({ StackName: fullStackName }),
+    );
+    expect(finalResponse.Stacks?.[0].StackStatus).toEqual('CREATE_COMPLETE');
+  }),
+);

packages/@aws-cdk/toolkit-lib/lib/actions/deploy/index.ts

@@ -1,7 +1,7 @@
 import type { StackSelector } from '../../api/cloud-assembly';
 import type { Tag } from '../../api/tags';
 
-export type DeploymentMethod = DirectDeployment | ChangeSetDeployment | HotswapDeployment;
+export type DeploymentMethod = DirectDeployment | ChangeSetDeployment | ExecuteChangeSetDeployment | HotswapDeployment;
 
 /**
  * Use stack APIs to the deploy stack changes
@@ -44,6 +44,22 @@ export interface ChangeSetDeployment {
   readonly revertDrift?: boolean;
 }
 
+/**
+ * Execute an existing change set that was previously created
+ *
+ * This bypasses synthesis and stack selection entirely.
+ * The stack name and change set name must refer to an existing change set
+ * in REVIEW_IN_PROGRESS or CREATE_COMPLETE status.
+ */
+export interface ExecuteChangeSetDeployment {
+  readonly method: 'execute-change-set';
+
+  /**
+   * The name of the change set to execute.
+   */
+  readonly changeSetName: string;
+}
+
 /**
  * Perform a 'hotswap' deployment to deploy a stack changes
  *

packages/@aws-cdk/toolkit-lib/lib/actions/deploy/private/deployment-method.ts

@@ -1,16 +1,7 @@
-import type { ChangeSetDeployment, DeploymentMethod } from '..';
+import type { ChangeSetDeployment, DeploymentMethod, ExecuteChangeSetDeployment } from '..';
 
 export const DEFAULT_DEPLOY_CHANGE_SET_NAME = 'cdk-deploy-change-set';
 
-/**
- * Execute a previously created change set.
- * This is an internal deployment method used by the two-phase deploy flow.
- */
-export interface ExecuteChangeSetDeployment {
-  readonly method: 'execute-change-set';
-  readonly changeSetName: string;
-}
-
 /**
  * A change set deployment that will execute.
  */
@@ -42,6 +33,13 @@ export function isNonExecutingChangeSetDeployment(method?: DeploymentMethod): me
   return isChangeSetDeployment(method) && (method.execute === false);
 }
 
+/**
+ * Returns true if the deployment method is a execute-change-set deployment.
+ */
+export function isExecuteChangeSetDeployment(method?: DeploymentMethod): method is ExecuteChangeSetDeployment {
+  return method?.method === 'execute-change-set';
+}
+
 /**
  * Create an ExecuteChangeSetDeployment from a ChangeSetDeployment.
  */

packages/@aws-cdk/toolkit-lib/lib/api/deployments/deploy-stack.ts

@@ -13,9 +13,9 @@ import * as uuid from 'uuid';
 import { AssetManifestBuilder } from './asset-manifest-builder';
 import { publishAssets } from './asset-publishing';
 import { addMetadataAssetsToManifest } from './assets';
-import type {
+import {
+  type ParameterChanges,
   ParameterValues,
-  ParameterChanges,
 } from './cfn-api';
 import {
   changeSetHasNoChanges,
@@ -26,7 +26,7 @@ import {
 } from './cfn-api';
 import { determineAllowCrossAccountAssetPublishing } from './checks';
 import type { DeployStackResult, SuccessfulDeployStackResult } from './deployment-result';
-import type { ChangeSetDeployment, DeploymentMethod, DirectDeployment } from '../../actions/deploy';
+import type { ChangeSetDeployment, DeploymentMethod, DirectDeployment, ExecuteChangeSetDeployment } from '../../actions/deploy';
 import { DEFAULT_DEPLOY_CHANGE_SET_NAME } from '../../actions/deploy/private/deployment-method';
 import { DeploymentError, DeploymentErrorCodes, ToolkitError } from '../../toolkit/toolkit-error';
 import { formatErrorMessage } from '../../util';
@@ -41,7 +41,6 @@ import type { IoHelper } from '../io/private';
 import type { ResourcesToImport } from '../resource-import';
 import { StackActivityMonitor } from '../stack-events';
 import { EarlyValidationReporter } from './early-validation';
-import type { ExecuteChangeSetDeployment } from '../../actions/deploy/private/deployment-method';
 
 export interface DeployStackOptions {
   /**
@@ -127,7 +126,7 @@ export interface DeployStackOptions {
    *
    * @default - Change set with defaults
    */
-  readonly deploymentMethod?: DeploymentMethod | ExecuteChangeSetDeployment;
+  readonly deploymentMethod?: DeploymentMethod;
 
   /**
    * The collection of extra parameters
@@ -194,12 +193,28 @@ export async function deployStack(options: DeployStackOptions, ioHelper: IoHelpe
   const stackArtifact = options.stack;
   const stackEnv = options.resolvedEnvironment;
 
-  let deploymentMethod = options.deploymentMethod ?? { method: 'change-set' };
+  const inputMethod = options.deploymentMethod ?? { method: 'change-set' };
+  let deploymentMethod: DeploymentMethod = inputMethod;
+
   options.sdk.appendCustomUserAgent(options.extraUserAgent);
   const cfn = options.sdk.cloudFormation();
   const deployName = options.deployName || stackArtifact.stackName;
   let cloudFormationStack = await CloudFormationStack.lookup(cfn, deployName);
 
+  // execute-change-set: skip template/asset work, go straight to FullCloudFormationDeployment
+  if (deploymentMethod.method === 'execute-change-set') {
+    const fullDeployment = new FullCloudFormationDeployment(
+      deploymentMethod,
+      options,
+      cloudFormationStack,
+      stackArtifact,
+      new ParameterValues({}, {}),
+      {},
+      ioHelper,
+    );
+    return fullDeployment.performDeployment();
+  }
+
   if (cloudFormationStack.stackStatus.isCreationFailure) {
     await ioHelper.defaults.debug(
       `Found existing stack ${deployName} that had previously failed creation. Deleting it before attempting to re-create it.`,

packages/@aws-cdk/toolkit-lib/lib/api/deployments/deployments.ts

@@ -18,7 +18,6 @@ import { deployStack, destroyStack } from './deploy-stack';
 import type { DeployStackResult, SuccessfulDeployStackResult } from './deployment-result';
 import type { ChangeSetDeployment, DeploymentMethod } from '../../actions/deploy';
 import { DEFAULT_DEPLOY_CHANGE_SET_NAME } from '../../actions/deploy/private/deployment-method';
-import type { ExecuteChangeSetDeployment } from '../../actions/deploy/private/deployment-method';
 import { DeploymentError, ToolkitError } from '../../toolkit/toolkit-error';
 import { formatErrorMessage } from '../../util';
 import type { SdkProvider } from '../aws-auth/private';
@@ -92,7 +91,7 @@ export interface DeployStackOptions {
    *
    * @default - Change set with default options
    */
-  readonly deploymentMethod?: DeploymentMethod | ExecuteChangeSetDeployment;
+  readonly deploymentMethod?: DeploymentMethod;
 
   /**
    * Force deployment, even if the deployed template is identical to the one we are about to deploy.

packages/@aws-cdk/toolkit-lib/lib/api/work-graph/work-graph.ts

@@ -6,6 +6,12 @@ import type { IoHelper } from '../io/private';
 export type Concurrency = number | Record<WorkNode['type'], number>;
 
 export class WorkGraph {
+  /**
+   * A helper to declare a noop action.
+   */
+  public static readonly NOOP: (..._: any[]) => any = () => {
+  };
+
   public readonly nodes: Record<string, WorkNode>;
   private readonly readyPool: Array<WorkNode> = [];
   private readonly lazyDependencies = new Map<string, string[]>();

packages/@aws-cdk/toolkit-lib/lib/toolkit/toolkit.ts

@@ -39,6 +39,7 @@ import { AssetBuildTime, type DeployOptions } from '../actions/deploy';
 import {
   buildParameterMap,
   isChangeSetDeployment,
+  isExecuteChangeSetDeployment,
   isExecutingChangeSetDeployment,
   isNonExecutingChangeSetDeployment,
   type PrivateDeployOptions,
@@ -95,7 +96,7 @@ import { ResourceMigrator } from '../api/resource-import';
 import { tagsForStack } from '../api/tags/private';
 import { DEFAULT_TOOLKIT_STACK_NAME } from '../api/toolkit-info';
 import type { AssetBuildNode, AssetPublishNode, Concurrency, StackNode } from '../api/work-graph';
-import { WorkGraphBuilder, buildDestroyWorkGraph } from '../api/work-graph';
+import { WorkGraph, WorkGraphBuilder, buildDestroyWorkGraph } from '../api/work-graph';
 import type { AssemblyData, RefactorResult, StackDetails, SuccessfulDeployStackResult } from '../payloads';
 import { PermissionChangeType } from '../payloads';
 import { formatErrorMessage, formatTime, obscureTemplate, serializeStructure, validateSnsTopicArn } from '../util';
@@ -557,9 +558,8 @@ export class Toolkit extends CloudAssemblySourceBuilder {
     };
 
     await workGraph.doParallel(graphConcurrency, {
-      deployStack: async () => {
-        // No-op: we're only publishing assets, not deploying
-      },
+      // No-op: we're only publishing assets, not deploying
+      deployStack: WorkGraph.NOOP,
       buildAsset: this.createBuildAssetFunction(ioHelper, deployments, undefined),
       publishAsset: this.createPublishAssetFunction(ioHelper, deployments, undefined, options.force),
     });
@@ -620,9 +620,11 @@ export class Toolkit extends CloudAssemblySourceBuilder {
     }
 
     const deployments = await this.deploymentsForAction('deploy');
-    const migrator = new ResourceMigrator({ deployments, ioHelper });
 
-    await migrator.tryMigrateResources(stackCollection, options);
+    if (!isExecuteChangeSetDeployment(options.deploymentMethod)) {
+      const migrator = new ResourceMigrator({ deployments, ioHelper });
+      await migrator.tryMigrateResources(stackCollection, options);
+    }
 
     const parameterMap = buildParameterMap(options.parameters?.parameters);
 
@@ -637,6 +639,21 @@ export class Toolkit extends CloudAssemblySourceBuilder {
     const stackOutputs: { [key: string]: any } = {};
     const outputsFile = options.outputsFile;
 
+    const { buildAsset, publishAsset } = (() => {
+      if (isExecuteChangeSetDeployment(options.deploymentMethod)) {
+        // No-op: assets are already published
+        return {
+          buildAsset: WorkGraph.NOOP,
+          publishAsset: WorkGraph.NOOP,
+        };
+      }
+
+      return {
+        buildAsset: this.createBuildAssetFunction(ioHelper, deployments, options.roleArn),
+        publishAsset: this.createPublishAssetFunction(ioHelper, deployments, options.roleArn, options.forceAssetPublishing),
+      };
+    })();
+
     const deployStack = async (stackNode: StackNode) => {
       const stack = stackNode.stack;
       if (stackCollection.stackCount !== 1) {
@@ -926,8 +943,8 @@ export class Toolkit extends CloudAssemblySourceBuilder {
 
     await workGraph.doParallel(graphConcurrency, {
       deployStack,
-      buildAsset: this.createBuildAssetFunction(ioHelper, deployments, options.roleArn),
-      publishAsset: this.createPublishAssetFunction(ioHelper, deployments, options.roleArn, options.forceAssetPublishing),
+      buildAsset,
+      publishAsset,
     });
 
     return ret;

packages/@aws-cdk/toolkit-lib/test/api/deployments/deploy-stack.test.ts

@@ -256,6 +256,45 @@ test('call CreateStack when method=direct and the stack doesnt exist yet', async
   expect(mockCloudFormationClient).toHaveReceivedCommand(CreateStackCommand);
 });
 
+test('execute-change-set describes and executes an existing change set', async () => {
+  // GIVEN - stack exists
+  mockCloudFormationClient.on(DescribeStacksCommand).resolves({
+    Stacks: [{ ...baseResponse }],
+  });
+  mockCloudFormationClient.on(DescribeChangeSetCommand).resolves({
+    Status: 'CREATE_COMPLETE',
+    ChangeSetName: 'MyChangeSet',
+    Changes: [],
+  });
+
+  // WHEN
+  await testDeployStack({
+    ...standardDeployStackArguments(),
+    deploymentMethod: { method: 'execute-change-set', changeSetName: 'MyChangeSet' },
+  });
+
+  // THEN - should execute the change set without creating a new one
+  expect(mockCloudFormationClient).toHaveReceivedCommand(ExecuteChangeSetCommand);
+  expect(mockCloudFormationClient).not.toHaveReceivedCommand(CreateChangeSetCommand);
+});
+
+test('execute-change-set throws if change set is not ready', async () => {
+  // GIVEN
+  mockCloudFormationClient.on(DescribeStacksCommand).resolves({
+    Stacks: [{ ...baseResponse }],
+  });
+  mockCloudFormationClient.on(DescribeChangeSetCommand).resolves({
+    Status: 'FAILED',
+    StatusReason: 'some reason',
+  });
+
+  // WHEN/THEN
+  await expect(testDeployStack({
+    ...standardDeployStackArguments(),
+    deploymentMethod: { method: 'execute-change-set', changeSetName: 'MyChangeSet' },
+  })).rejects.toThrow('not ready for execution');
+});
+
 test('call UpdateStack when method=direct and the stack exists already', async () => {
   // WHEN
   mockCloudFormationClient.on(DescribeStacksCommand).resolves({

packages/aws-cdk/README.md

@@ -409,6 +409,10 @@ be deployed and then executes it. This behavior can be controlled with the
 - `--method=prepare-change-set`: create the change set but don't execute it.
   This is useful if you have external tools that will inspect the change set or
   you have an approval process for change sets.
+- `--method=execute-change-set`: execute a previously created change set. This
+  bypasses synthesis and stack selection entirely. Requires `--change-set-name`
+  and exactly one stack name. This is useful for two-step deployment workflows
+  where you first review a change set and then execute it.
 - `--method=direct`: do not create a change set but apply the change immediately.
   This is typically a bit faster than creating a change set, but it loses
   the progress information.
@@ -428,8 +432,21 @@ set to make it easier to later execute:
 $ cdk deploy --method=prepare-change-set --change-set-name MyChangeSetName
 ```
 
-For more control over when stack changes are deployed, the CDK can generate a
-CloudFormation change set but not execute it.
+To review a change set before executing it, use a two-step workflow:
+
+```console
+$ # Step 1: Create the change set without executing it
+$ cdk deploy MyStack --method=prepare-change-set --change-set-name MyChangeSetName
+
+$ # Step 2: Review the change set (e.g., in the AWS Console or via CLI)
+
+$ # Step 3: Execute the change set with approval
+$ cdk deploy MyStack --method=execute-change-set --change-set-name MyChangeSetName
+```
+
+When using `--method=execute-change-set`, options like `--force`, `--parameters`,
+`--no-rollback`, `--import-existing-resources`, and `--revert-drift` are ignored
+since the change set has already been created.
 
 #### Import existing resources