feat(cli): display warning when --role-arn is used with gc command (#893)

The gc command currently ignores the --role-arn parameter and always
uses the user's default credentials, regardless of whether a role ARN is
specified. This can potentially lead to silent failures, permission
issues, as well as a bad user experience due to confusion.

This pr adds a check to throw a warning when the --role-arn parameter is
used in the gc command. This helps improve user experience and avoid
mismanaged expectations.

A consideration to throw an error was made. However, this could be a
breaking change for existing ci/cd pipeline users. Therefore, this idea
was discarded

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

Author: dgandhi62

packages/aws-cdk/lib/cli/cli.ts

@@ -475,6 +475,11 @@ export async function exec(args: string[], synthesizer?: Synthesizer): Promise<n
         if (args.bootstrapStackName) {
           await ioHost.defaults.warn('--bootstrap-stack-name is deprecated and will be removed when gc is GA. Use --toolkit-stack-name.');
         }
+        // roleArn is defined for when cloudformation is invoked
+        // This conflicts with direct sdk calls existing in the gc command to s3 and ecr
+        if (args.roleArn) {
+          await ioHost.defaults.warn('The --role-arn option is not supported for the gc command and will be ignored.');
+        }
         return cli.garbageCollect(args.ENVIRONMENTS, {
           action: args.action,
           type: args.type,

packages/aws-cdk/test/cli/cli.test.ts

@@ -51,6 +51,14 @@ jest.mock('../../lib/cli/parse-command-line-arguments', () => ({
       if (args.includes('ts')) {
         result = { ...result, language: 'typescript' };
       }
+    } else if (args.includes('gc')) {
+      result = { ...result, _: ['gc'] };
+
+      // Handle role-arn flag for gc command validation testing
+      // This simulates parser behavior to test that the CLI properly rejects roleArn
+      if (args.includes('--role-arn')) {
+        result = { ...result, roleArn: 'arn:aws:iam::123456789012:role/TestRole' };
+      }
     }
 
     // Handle notices flags
@@ -427,3 +435,49 @@ describe('notices configuration tests', () => {
     );
   });
 });
+
+describe('gc command tests', () => {
+  let originalCliIoHostInstance: any;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    originalCliIoHostInstance = CliIoHost.instance;
+  });
+
+  afterEach(() => {
+    CliIoHost.instance = originalCliIoHostInstance;
+  });
+
+  test('should warn when --role-arn is used with gc command', async () => {
+    const gcSpy = jest.spyOn(cdkToolkitModule.CdkToolkit.prototype, 'garbageCollect').mockResolvedValue();
+
+    // Make exec use our TestIoHost and adds properties to TestIoHost to match CliIoHost
+    const warnSpy = jest.fn();
+    (ioHost as any).defaults = { warn: warnSpy, debug: jest.fn(), result: jest.fn() };
+    (ioHost as any).asIoHelper = () => ioHelper;
+    (ioHost as any).logLevel = 'info';
+    jest.spyOn(CliIoHost, 'instance').mockReturnValue(ioHost as any);
+
+    const mockConfig = {
+      loadConfigFiles: jest.fn().mockResolvedValue(undefined),
+      settings: {
+        get: jest.fn().mockImplementation((key: string[]) => {
+          if (key[0] === 'unstable') return ['gc'];
+          return [];
+        }),
+      },
+      context: {
+        get: jest.fn().mockReturnValue([]),
+      },
+    };
+
+    Configuration.fromArgsAndFiles = jest.fn().mockResolvedValue(mockConfig);
+
+    await exec(['gc', '--unstable=gc', '--role-arn', 'arn:aws:iam::123456789012:role/TestRole']);
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      'The --role-arn option is not supported for the gc command and will be ignored.',
+    );
+    expect(gcSpy).toHaveBeenCalled();
+  });
+});