Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/okruti-raghuraj/aws-1/llms.txt

Use this file to discover all available pages before exploring further.

MyPipelineAppStage is the deployment unit that the pipeline operates on. Rather than deploying individual stacks directly, CDK Pipelines works with cdk.Stage subclasses — each stage encapsulates one or more stacks that should always be deployed together. This abstraction is what makes it straightforward to promote the same set of stacks through dev, staging, and production environments without duplicating configuration.

​
What Is a CDK Stage?

A cdk.Stage is a scope that groups related stacks into a single deployable unit. When the pipeline executes, it treats each stage as an atomic wave: all stacks inside a stage are synthesized together, and the pipeline will not advance to the next stage until every stack in the current one has deployed successfully. Key properties of a CDK stage:
  • Atomic deployment — all stacks within a stage succeed or fail together as a group.
  • Environment isolation — each stage can target a different account and region, enabling cross-account pipelines.
  • Multiple stages per pipeline — you can chain dev → staging → prod stages in a single pipeline definition, each receiving the same set of stacks but deploying to different environments.
  • Pre/post hooks — stages accept optional validation steps (integration tests, approval gates) that run before or after the stacks are deployed.

​
Current Implementation

The file lib/my-pipeline-app-stage.ts ships fully commented out, matching the same template approach used by LambdaStack. Activate it by uncommenting the file once you are ready to wire the application into the pipeline.
aws-cdk-pipeline/lib/my-pipeline-app-stage.ts
// import * as cdk from 'aws-cdk-lib';
// import { Construct } from "constructs";
// import { MyLambdaStack } from './my-pipeline-lambda-stack';

// export class MyPipelineAppStage extends cdk.Stage {
    
//     constructor(scope: Construct, id: string, props?: cdk.StageProps) {
//       super(scope, id, props);
  
//       const lambdaStack = new MyLambdaStack(this, 'LambdaStack');      
//     }
// }
The commented-out file imports from './my-pipeline-lambda-stack' while the actual Lambda stack file is named aws-cdk-pipeline-lambda-stack.ts. Update the import path when you uncomment to match the real filename.

​
Uncommented Implementation

After removing the comment markers and correcting the import, the stage looks like this: 
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { LambdaStack } from './aws-cdk-pipeline-lambda-stack';

export class MyPipelineAppStage extends cdk.Stage {
    constructor(scope: Construct, id: string, props?: cdk.StageProps) {
        super(scope, id, props);
        const lambdaStack = new LambdaStack(this, 'LambdaStack');
    }
}
Passing this (the stage) as the scope to LambdaStack registers the stack under the stage. CDK automatically namespaces the CloudFormation stack name as <StageId>-LambdaStack, so you can deploy the same stage to multiple environments without name collisions.

​
Adding a Stage to the Pipeline

Once MyPipelineAppStage is active, attach it to the pipeline inside AwsCdkPipelineStack: 
pipeline.addStage(new MyPipelineAppStage(this, 'Deploy', {
  env: { account: '602143770054', region: 'ap-south-1' }
}));
addStage appends the stage after the pipeline’s built-in self-mutation stage. The env passed here pins the stage to the same target account and region used in the app entry point, ensuring stacks land in the intended environment.

​
Multi-Environment Deployment

One of the primary reasons to use cdk.Stage is the ability to promote the same application across multiple environments by calling addStage multiple times with different env values: 
pipeline.addStage(new MyPipelineAppStage(this, 'Dev', {
  env: { account: 'DEV_ACCOUNT_ID', region: 'ap-south-1' }
}));

pipeline.addStage(new MyPipelineAppStage(this, 'Prod', {
  env: { account: 'PROD_ACCOUNT_ID', region: 'ap-south-1' }
}));
The pipeline will deploy to Dev first and only promote to Prod if every stack in the Dev stage reaches CREATE_COMPLETE or UPDATE_COMPLETE. For cross-account deployments, make sure both the Dev and Prod accounts have been bootstrapped with cdk bootstrap --trust <PIPELINE_ACCOUNT_ID>.
Stage vs Stack — a stage represents an environment (dev, staging, production) and can contain many stacks. A stack represents a single service or component (a Lambda function, a database, an API Gateway). Use stages to separate environments; use stacks to separate concerns within an environment.
Add pre- or post-deployment validation steps to a stage to catch regressions before they reach production. Pass a pre or post array of Step objects to addStage:
import { ShellStep } from 'aws-cdk-lib/pipelines';

pipeline.addStage(new MyPipelineAppStage(this, 'Dev', {
  env: { account: 'DEV_ACCOUNT_ID', region: 'ap-south-1' }
}), {
  pre: [
    new ShellStep('Validate', {
      commands: ['echo "Running pre-deploy checks..."', 'npm test']
    })
  ],
  post: [
    new ShellStep('IntegrationTest', {
      commands: ['curl -f $ENDPOINT_URL || exit 1']
    })
  ]
});
The pre steps run before any stack in the stage is deployed; post steps run after all stacks complete successfully.

Build docs developers (and LLMs) love

Get started for freeTalk to us