feat(pipelines): add assumeRole parameter to CodeBuildStep

[umbertocicciaa]

Issue # (if applicable)

Closes #18272

Ai Usage

• Claude Code Sonnet 5 (Medium) + ponytail skill https://github.com/DietrichGebert/ponytail
• Generating unit tests and integration tests

Reason for this change

pipelines.CodeBuildStep has no built-in way to run its commands under a different IAM role. This matters for cross-account deployment pipelines, where the CodeBuild project's own role can't reach resources in the deployed (target) account, e.g. invoking a Lambda function to run a DB migration, or seeding Cognito users for integration tests. Users currently have to hand-roll this with aws sts assume-role calls inside commands, wiring up the trust policy and sts:AssumeRole permission themselves each time.

Description of changes

Added an assumeRole?: iam.IRole property to CodeBuildStepProps / CodeBuildStep. When set:

• The CodeBuild project's role is granted sts:AssumeRole on the given role (assumeRole.grant(project.grantPrincipal, 'sts:AssumeRole')).
• Three commands are prepended to the buildspec's install phase, before any user-supplied installCommands, which configure a named AWS CLI profile (cdk-assume-role) pointed at the role and export it as the active profile:

aws configure --profile cdk-assume-role set role_arn <roleArn>
aws configure --profile cdk-assume-role set credential_source EcsContainer
export AWS_PROFILE=cdk-assume-role

This means all of commands (and any commands after it in the same build) run under assumeRole without the user needing to write any of this themselves.

This follows the exact workaround proposed in the issue, and reuses two patterns already present in the codebase rather than inventing new ones:

• The role/actionRole plumbing already threaded from CodeBuildStep → CodeBuildFactoryProps → CodeBuildFactory.produceAction is extended the same way for assumeRole.
• The "grant sts:AssumeRole on an optional role" idiom already used in docker-credentials.ts (grantee.grantPrincipal.addToPrincipalPolicy(...)) is reused via IRole.grant().

Files changed:

• packages/aws-cdk-lib/pipelines/lib/codepipeline/codebuild-step.ts new assumeRole prop.
• packages/aws-cdk-lib/pipelines/lib/codepipeline/private/codebuild-factory.ts new assumeRole on CodeBuildFactoryProps, threaded through fromCodeBuildStep, grant + buildspec command injection in produceAction.
• packages/aws-cdk-lib/pipelines/test/codepipeline/codebuild-step.test.ts new unit test.

Describe any new or updated permissions being added

When assumeRole is set, the CodeBuild project's execution role is granted:

{
  "Effect": "Allow",
  "Action": "sts:AssumeRole",
  "Resource": "<assumeRole ARN>"
}

No other permissions are added, and nothing changes for callers who don't set assumeRole (opt-in, default undefined).

Description of how you validated changes

• Added a unit test (assumeRole grants sts:AssumeRole and injects profile commands) in codebuild-step.test.ts, following the existing style of the neighboring role passed it used for project and code build action test. It asserts:
  1. An AWS::IAM::Policy statement granting sts:AssumeRole on the target role's ARN is attached to the CodeBuild project's role.
  2. The generated AWS::CodeBuild::Project buildspec's install phase contains the aws configure / export AWS_PROFILE commands.
• Ran the full pipelines unit test suite locally: yarn test pipelines → 211/212 passing (all passing, including the new test), no regressions in the other 21 test suites.

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

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

[aws-cdk-automation]

The pull request linter fails with the following errors:

❌ Features must contain a change to an integration test file and the resulting snapshot.

If you believe this pull request should receive an exemption, please comment and provide a justification. A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed, add Clarification Request to a comment.

✅ A exemption request has been requested. Please wait for a maintainer's review.

[umbertocicciaa]

The pull request linter fails with the following errors:

❌ Features must contain a change to an integration test file and the resulting snapshot.

If you believe this pull request should receive an exemption, please comment and provide a justification. A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed, add Clarification Request to a comment.

Require an exception (or am i missing something?)