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.

Every push to the aws-pipeline branch of the RaghurajSingh/SMS GitHub repository kicks off a fully automated chain: CodePipeline pulls the source, a CodeBuild project synthesizes CloudFormation templates, the pipeline updates its own definition if needed, and then each application stage is deployed in sequence. The entire flow is defined as TypeScript code and lives alongside the application it ships.

​
Pipeline Stages

​
1. Source

The pipeline watches a specific GitHub repository and branch. When a commit lands, CodePipeline automatically starts a new execution: 
CodePipelineSource.gitHub('RaghurajSingh/SMS', 'aws-pipeline')
  • Repository: RaghurajSingh/SMS
  • Branch: aws-pipeline
  • Trigger: Any push to the branch (CodeStar Connections webhook)
No polling is used — the connection is event-driven, so the pipeline starts within seconds of a push.

​
2. Synth

The Synth step is a ShellStep that runs inside a managed CodeBuild environment. It installs dependencies, compiles TypeScript, and synthesizes the CloudFormation templates: 
npm ci          # clean install from package-lock.json
npm run build   # tsc — compiles TypeScript to JavaScript
npx cdk synth   # synthesizes all stacks to cdk.out/
The output of this step is the cdk.out/ cloud assembly — a directory of CloudFormation templates and assets that fully describes every stack in the app.

​
3. Self-Mutation

After synthesis, CDK Pipelines compares the newly produced pipeline definition against the currently deployed CodePipeline. If the pipeline structure has changed (new stages, updated build commands, different source branch), the pipeline updates itself before proceeding. This update step runs as a separate CodePipeline action.
Self-mutation means you never need to run cdk deploy again after the first bootstrap. Any change to the pipeline definition — adding a deployment stage, changing environment variables, updating the synth commands — is automatically applied on the next push, because the pipeline redeploys itself before it deploys your application.

​
4. Deploy

Once the pipeline is up to date, it deploys each cdk.Stage that was added via pipeline.addStage(...). Stages run in the order they were added and can contain one or more CloudFormation stacks.

​
Pipeline Stack Code

The entire pipeline is defined in a single CDK stack: 
// lib/aws-cdk-pipeline-stack.ts
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { CodePipeline, CodePipelineSource, ShellStep } from 'aws-cdk-lib/pipelines';

export class AwsCdkPipelineStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const pipeline = new CodePipeline(this, 'Pipeline', {
      pipelineName: 'TestPipeline',
      crossAccountKeys: false,
      synth: new ShellStep('synth', {
        input: CodePipelineSource.gitHub('RaghurajSingh/SMS', 'aws-pipeline'),
        commands: [
          'npm ci',
          'npm run build',
          'npx cdk synth'
        ],
      }),
    });
  }
}
The stack is instantiated in bin/aws-cdk-pipeline.ts with an explicit AWS account and region: 
// bin/aws-cdk-pipeline.ts
const app = new cdk.App();
new AwsCdkPipelineStack(app, 'AwsCdkPipelineStack', {
  env: { account: '602143770054', region: 'ap-south-1' },
});
app.synth();
Pinning env is required for CDK Pipelines — environment-agnostic stacks cannot be used because the pipeline must know where to deploy.

​
crossAccountKeys: false

By default, CDK Pipelines creates a customer-managed KMS key to encrypt the CodePipeline artifact bucket. Setting crossAccountKeys: false disables this and uses SSE-S3 (AWS-managed encryption) instead.

crossAccountKeys: true (default)

Creates a KMS Customer Managed Key. Required when the pipeline deploys to a different AWS account. Adds ~$1/month per key in KMS charges.

crossAccountKeys: false

Uses SSE-S3 (AES-256) for the artifact bucket. No KMS cost. Sufficient when all pipeline stages deploy into the same account. Used in this project.
If you later add a deployment stage that targets a different AWS account, you must set crossAccountKeys: true and redeploy the pipeline stack, because cross-account artifact access requires a KMS key that can be shared via key policy.

​
Self-Mutation Explained

The self-mutation step is what makes CDK Pipelines fundamentally different from a hand-rolled CodePipeline. When the pipeline runs, it executes a cdk deploy of its own pipeline stack using the freshly synthesized cloud assembly. Only after the pipeline stack is confirmed up to date does execution continue to the application deployment stages.
Once the pipeline is bootstrapped with a single cdk deploy, you never need to run cdk deploy locally again. The pipeline becomes the sole mechanism for infrastructure changes — your git history is your deployment history.

​
Adding Application Stages

Application workloads are added to the pipeline using the cdk.Stage pattern. A Stage groups one or more cdk.Stack instances that represent a logical deployment environment (for example, staging or production). The project already includes the scaffolding for a Lambda deployment stage, currently commented out in both source files. The code below reflects the actual file contents — every line is commented out and nothing is active yet: 
// lib/my-pipeline-app-stage.ts  (entire file is commented out — planned, not active)
// 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');
//     }
// }

// lib/aws-cdk-pipeline-lambda-stack.ts  (entire file is commented out — planned, not active)
// import * as cdk from 'aws-cdk-lib';
// import { Construct } from 'constructs';
// import { Function, InlineCode, Runtime } from 'aws-cdk-lib/aws-lambda';

// export class LambdaStack extends cdk.Stack {
//     constructor(scope: Construct, id: string, props?: cdk.StackProps) {
//         super(scope, id, props);
//
//         new Function(this, 'lambdafunction', {
//             runtime: Runtime.NODEJS_12_X,
//             handler: 'index.handler',
//             code: new InlineCode('exports.handler = _ => "Hello, CDK";')
//         });
//     }
// }
To activate the stage, uncomment both files and add the stage to the pipeline in AwsCdkPipelineStack: 
import { MyPipelineAppStage } from './my-pipeline-app-stage';

// Inside the constructor, after the pipeline is created:
pipeline.addStage(new MyPipelineAppStage(this, 'Deploy'));
Push the change — the pipeline will self-mutate to add the new Deploy stage, then execute it automatically.

​
Deployment Flows

1

Bootstrap (first time only)

Prepare your AWS account and region for CDK deployments. This creates the CDK bootstrap stack (S3 bucket, ECR repository, IAM roles) that CodePipeline will use.
npx cdk bootstrap aws://602143770054/ap-south-1
2

Authenticate with GitHub

Create an AWS CodeStar Connection to GitHub in the ap-south-1 region and approve it in the AWS Console. CDK Pipelines uses this connection as the webhook source trigger.
3

Deploy the pipeline stack once

Run cdk deploy from your local machine exactly once to create the CodePipeline pipeline in AWS.
npm run build
npx cdk deploy AwsCdkPipelineStack
4

Push to trigger the pipeline

From this point on, every push to the aws-pipeline branch triggers the pipeline automatically. No further local cdk deploy commands are needed.
git add .
git commit -m "feat: add Lambda deployment stage"
git push origin aws-pipeline
5

Monitor in the AWS Console

Open CodePipeline → TestPipeline in the AWS Console (ap-south-1) to watch the Source, Synth, self-mutation, and Deploy stages execute in real time.
Use npx cdk diff before pushing to preview which CloudFormation changes your commit will produce. This is purely informational — the pipeline will apply the changes regardless — but it helps catch unexpected resource replacements before they happen.

Build docs developers (and LLMs) love

Get started for freeTalk to us