fix(core): ensure CloudFormation ChangeSets receive tags with explicitStackTags flag

When the @aws-cdk/core:explicitStackTags feature flag was introduced in v2.205.0,
it inadvertently caused CloudFormation ChangeSets to not receive stack tags,
breaking deployments with SCP policies requiring tags on ChangeSets.

This fix adds a new property 'applyToChangeSets' to TagProps (default: true) that
ensures tags are still applied to the stack for ChangeSet purposes, while maintaining
the correct behavior of not duplicating tags on resources.

Fixes regression introduced in v2.205.0 where ChangeSets lost their tags.

Author: CDK Contributor

packages/aws-cdk-lib/core/lib/tag-aspect.ts

@@ -3,6 +3,7 @@ import { Annotations } from './annotations';
 import { IAspect, Aspects, AspectOptions } from './aspect';
 import { UnscopedValidationError } from './errors';
 import { FeatureFlags } from './feature-flags';
+import { Stack } from './stack';
 import * as cxapi from '../../cx-api';
 import { mutatingAspectPrio32333 } from './private/aspect-prio';
 import { ITaggable, ITaggableV2, TagManager } from './tag-manager';
@@ -38,6 +39,18 @@ export interface TagProps {
    */
   readonly includeResourceTypes?: string[];
 
+  /**
+   * Whether to apply tags to CloudFormation ChangeSets
+   * 
+   * This ensures tags are applied to ChangeSets even when the 
+   * explicitStackTags feature flag excludes stack-level tags.
+   * This is important for compliance with SCP policies that 
+   * require tags on ChangeSets.
+   * 
+   * @default true
+   */
+  readonly applyToChangeSets?: boolean;
+
   /**
    * Priority of the tag operation
    *
@@ -186,7 +199,18 @@ export class Tags {
    */
   public add(key: string, value: string, props: TagProps = {}) {
     // Implicitly add `aws:cdk:stack` to the `excludeResourceTypes` array in modern behavior
+    // BUT: If applyToChangeSets is true (default), we need to ensure ChangeSets still get tagged
     if (this.explicitStackTags && !props.includeResourceTypes?.includes('aws:cdk:stack')) {
+      // Check if we should still apply to ChangeSets
+      const applyToChangeSets = props.applyToChangeSets !== false;
+      
+      // If applyToChangeSets is true, we need to ensure the stack still gets the tags
+      // for ChangeSets, even though resources won't get them from the stack
+      if (applyToChangeSets && Stack.isStack(this.scope)) {
+        // Apply the tag directly to the stack for ChangeSet purposes
+        (this.scope as Stack).addStackTag(key, value);
+      }
+      
       props = {
         ...props,
         excludeResourceTypes: [...props.excludeResourceTypes ?? [], 'aws:cdk:stack'],

packages/aws-cdk-lib/core/test/integ.stack-tags-changeset.ts

@@ -0,0 +1,39 @@
+/**
+ * Integration test for stack tagging behavior with explicitStackTags feature flag.
+ * This test verifies that ChangeSets receive proper tags even when the explicitStackTags
+ * feature flag is enabled, ensuring compliance with SCP policies that require tags on ChangeSets.
+ */
+
+import { App, Stack, Tags, CfnOutput } from 'aws-cdk-lib';
+
+const app = new App({
+  context: {
+    '@aws-cdk/core:explicitStackTags': true,
+  },
+});
+
+// Stack with Tags.of(stack).add() - should apply to ChangeSets  
+const stack = new Stack(app, 'integ-stack-tags-changeset', {
+  env: { region: 'us-east-1' },
+});
+
+// Add tags using Tags.of(stack).add() - these should be applied to ChangeSets
+Tags.of(stack).add('Environment', 'IntegTest');
+Tags.of(stack).add('Project', 'CDK-Core');
+Tags.of(stack).add('Owner', 'CDK-Team');
+Tags.of(stack).add('CostCenter', 'Engineering');
+
+// Test the new applyToChangeSets property
+Tags.of(stack).add('ChangeSetTag', 'ShouldAppear');
+Tags.of(stack).add('NoChangeSetTag', 'ShouldNotAppear', { applyToChangeSets: false });
+
+// Add direct stack tags as well
+stack.addStackTag('DirectTag', 'DirectValue');
+
+// Add a simple resource to make the stack deployable
+new CfnOutput(stack, 'TestOutput', {
+  value: 'test-value',
+  description: 'Test output for integration test',
+});
+
+app.synth();

packages/aws-cdk-lib/core/test/tag-aspect-changeset.test.ts

@@ -0,0 +1,129 @@
+import { Annotations, App, Stack, Tags } from '../lib';
+import { getWarnings } from './util';
+
+describe('ChangeSet tagging with explicitStackTags', () => {
+  test('tags are applied to ChangeSets even when explicitStackTags is enabled', () => {
+    // GIVEN
+    const app = new App({
+      context: {
+        '@aws-cdk/core:explicitStackTags': true,
+      },
+    });
+    const stack = new Stack(app, 'TestStack');
+
+    // WHEN
+    Tags.of(stack).add('TestKey', 'TestValue');
+    Tags.of(stack).add('Environment', 'Production');
+    Tags.of(stack).add('Project', 'CDK-Fix');
+
+    // THEN
+    // Stack should have tags for ChangeSets
+    const stackTags = stack.tags.tagValues();
+    expect(stackTags).toHaveProperty('TestKey', 'TestValue');
+    expect(stackTags).toHaveProperty('Environment', 'Production');
+    expect(stackTags).toHaveProperty('Project', 'CDK-Fix');
+  });
+
+  test('applyToChangeSets can be disabled explicitly', () => {
+    // GIVEN
+    const app = new App({
+      context: {
+        '@aws-cdk/core:explicitStackTags': true,
+      },
+    });
+    const stack = new Stack(app, 'TestStack');
+
+    // WHEN
+    Tags.of(stack).add('TestKey', 'TestValue', { applyToChangeSets: false });
+
+    // THEN
+    // Stack should NOT have tags when applyToChangeSets is false
+    const stackTags = stack.tags.tagValues();
+    expect(Object.keys(stackTags)).toHaveLength(0);
+  });
+
+  test('legacy behavior is maintained when explicitStackTags is not enabled', () => {
+    // GIVEN
+    const app = new App({
+      context: {
+        '@aws-cdk/core:explicitStackTags': false,
+      },
+    });
+    const stack = new Stack(app, 'TestStack');
+
+    // WHEN
+    Tags.of(stack).add('TestKey', 'TestValue');
+
+    // THEN
+    // Stack should have tags (legacy behavior)
+    const stackTags = stack.tags.tagValues();
+    expect(stackTags).toHaveProperty('TestKey', 'TestValue');
+  });
+
+  test('direct stack tagging still works with addStackTag', () => {
+    // GIVEN
+    const app = new App({
+      context: {
+        '@aws-cdk/core:explicitStackTags': true,
+      },
+    });
+    const stack = new Stack(app, 'TestStack');
+
+    // WHEN
+    stack.addStackTag('DirectTag', 'DirectValue');
+
+    // THEN
+    const stackTags = stack.tags.tagValues();
+    expect(stackTags).toHaveProperty('DirectTag', 'DirectValue');
+  });
+
+  test('mixed tagging approaches work together', () => {
+    // GIVEN
+    const app = new App({
+      context: {
+        '@aws-cdk/core:explicitStackTags': true,
+      },
+    });
+    const stack = new Stack(app, 'TestStack');
+
+    // WHEN
+    stack.addStackTag('DirectTag', 'DirectValue');
+    Tags.of(stack).add('AspectTag', 'AspectValue');
+    Tags.of(stack).add('NoChangeSetTag', 'NoValue', { applyToChangeSets: false });
+
+    // THEN
+    const stackTags = stack.tags.tagValues();
+    expect(stackTags).toHaveProperty('DirectTag', 'DirectValue');
+    expect(stackTags).toHaveProperty('AspectTag', 'AspectValue');
+    expect(stackTags).not.toHaveProperty('NoChangeSetTag');
+  });
+
+  test('tags with tokens show warning but still apply to ChangeSets', () => {
+    // GIVEN
+    const app = new App({
+      context: {
+        '@aws-cdk/core:explicitStackTags': true,
+      },
+    });
+    const stack = new Stack(app, 'TestStack');
+
+    // WHEN
+    Tags.of(stack).add('StaticKey', 'StaticValue');
+    Tags.of(stack).add('TokenKey', stack.stackName); // This contains a token
+
+    // Synthesize to trigger warnings
+    app.synth();
+
+    // THEN
+    const warnings = getWarnings(app.synth());
+    // Should have warning about token tags
+    const tokenWarnings = warnings.filter(w => 
+      w.message.includes('Ignoring stack tags that contain deploy-time values')
+    );
+    expect(tokenWarnings.length).toBeGreaterThan(0);
+    
+    // But static tags should still be applied
+    const stackTags = stack.tags.tagValues();
+    expect(stackTags).toHaveProperty('StaticKey', 'StaticValue');
+  });
+});