(aws-codepipeline): usePipelineRoleForActions: true causes circular dependency error during deployment

[hemanth-m19]

Describe the bug

When setting the usePipelineRoleForActions: true property on the AWS CodePipeline L2 construct, deployment fails with a circular dependency error. This issue occurs despite a successful cdk synth.

ValidationError: Circular dependency between resources: [PipelineRoleDefaultPolicyC7A05455, PipelineC660917D]

Regression Issue

• Select this option if this issue appears to be a regression.

Last Known Working CDK Library Version

No response

Expected Behavior

The pipeline should deploy successfully and actions should use the pipeline's IAM role.

Current Behavior

Deployment fails with the following error:
ValidationError: Circular dependency between resources: [PipelineRoleDefaultPolicyC7A05455, PipelineC660917D]

Reproduction Steps

const pipeline = new codepipeline.Pipeline(this, 'Pipeline', {
  usePipelineRoleForActions: true,
});

const sourceStage = pipeline.addStage({ stageName: 'Source' });
const buildStage = pipeline.addStage({ stageName: 'Build' });

const sourceOutput = new codepipeline.Artifact();

sourceStage.addAction(
  new codepipeline_actions.CodeStarConnectionsSourceAction({
    owner: `some-owner`,
    repo: `some-repo-name`,
    triggerOnPush: true,
    connectionArn: 'arn:aws:codestar-connections:ap-southeast-2:123456789012:connection/12345678-abcd-12ab-34cdef5678gh',
    actionName: `some-repo-name_Source`,
    output: sourceOutput,
    branch: 'master',
}));

buildStage.addAction(new codepipeline_actions.CommandsAction({
  actionName: 'Commands',
  input: sourceOutput,
  commands: [
    'export MY_OUTPUT=my-key',
  ],
}));

Possible Solution

No response

Additional Information/Context

No response

AWS CDK Library version (aws-cdk-lib)

2.197.0

AWS CDK CLI version

2.1016.1

Node.js Version

v20.12.2

OS

Ubuntu-22.04

Language

TypeScript

Language Version

No response

Other information

It appears that enabling usePipelineRoleForActions causes a dependency loop between the pipeline role's policy and the pipeline itself.

[ykethan]

Hey @hemanth-m19 , Thank you for reporting this issue. I've reproduced and confirmed the circular dependency problem when using usePipelineRoleForActions: true with CodePipeline actions.

Reproduction

import * as codepipeline from 'aws-cdk-lib/aws-codepipeline';
import * as codepipeline_actions from 'aws-cdk-lib/aws-codepipeline-actions';

const pipeline = new codepipeline.Pipeline(this, 'Pipeline', {
  usePipelineRoleForActions: true,
});

const sourceStage = pipeline.addStage({ stageName: 'Source' });
const buildStage = pipeline.addStage({ stageName: 'Build' });

const sourceOutput = new codepipeline.Artifact();

sourceStage.addAction(
  new codepipeline_actions.CodeStarConnectionsSourceAction({
    owner: 'some-owner',
    repo: 'some-repo-name',
    triggerOnPush: true,
    connectionArn: '<arn>',
    actionName: 'some-name',
    output: sourceOutput,
    branch: 'master',
  })
);

buildStage.addAction(
  new codepipeline_actions.CommandsAction({
    actionName: 'Commands',
    input: sourceOutput,
    commands: ['export MY_OUTPUT=my-key'],
  })
);

The issue occurs during deployment (not synthesis), with the error:

ValidationError: Circular dependency between resources: [PipelineRoleDefaultPolicyC7A05455, PipelineC660917D]

When using the usePipelineRoleForActions: true option with AWS CodePipeline, a circular dependency is created between:

• PipelineRoleDefaultPolicyC7A05455 (the pipeline role's policy)
• PipelineC660917D (the pipeline resource itself)

This circular dependency occurs specifically when using certain action types like CodeStarConnectionsSourceAction and CommandsAction together.

Root Cause

Looking at packages/aws-cdk-lib/aws-codepipeline/lib/pipeline.ts, I found:

1. When usePipelineRoleForActions: true is set, the getRoleForAction method returns undefined for AWS-owned actions to use the pipeline's own role:

   if (!actionRole && this.isAwsOwned(action)) {
     if (this.usePipelineRoleForActions) {
       return undefined;  // Use pipeline role
     }
     // Otherwise generate a new role...
   }

2. The bound methods of actions like CodeStarConnectionsSourceAction and CommandsAction add permissions to the role passed via options.role:

   // In CodeStarConnectionsSourceAction.bound:
   options.role.addToPolicy(new iam.PolicyStatement({
     actions: ['codestar-connections:UseConnection'],
     resources: [this.props.connectionArn],
   }));

This appears to create the circular dependency during CloudFormation deployment because the pipeline requires its role and policy to be fully defined and role policy needs to include permissions for all actions but those permissions can't be determined until the pipeline is defined

Workarounds

Workaround 1: Don't use usePipelineRoleForActions (simpler)

Remove the option to use the default behavior where each action gets its own role:

const pipeline = new codepipeline.Pipeline(this, 'Pipeline', {
  // Do not include usePipelineRoleForActions: true
});

Workaround 2: Create a custom role with explicit trust policy

Create a shared role for your actions with explicit trust to the pipeline role:

// Create the pipeline first
const pipeline = new codepipeline.Pipeline(this, 'Pipeline');

// Create a custom action role with explicit trust relationship to pipeline role
const actionRole = new iam.Role(this, 'ActionRole', {
  assumedBy: new iam.ArnPrincipal(pipeline.role.roleArn),
});

// Use this role for actions
sourceStage.addAction(
  new codepipeline_actions.CodeStarConnectionsSourceAction({
    // ... other props
    role: actionRole,
  })
);

buildStage.addAction(
  new codepipeline_actions.CommandsAction({
    // ... other props 
    role: actionRole,
  })
);

Marking as P2 bug.
We greatly appreciate community contributions! If you are interested in implementing this, we'd be happy to review your Pull Request. Please review our contribution guidelines.