Welcome to the CDK CI/CD Wrapper

CDK CI/CD Wrapper

Documentation · Changelog · Join the community

Warning

[!WARNING] Experimental — pre-release. The developer experience documented below is the Autopilot (1.x) line, developed on main. Version 1.0.0 is published to npm but is not the latest dist-tag: npm install still resolves the stable 0.x (Blueprint) line (currently 0.4.3; 0.4.0 is deprecated — do not use it), whose API is not the one described here. To install the 1.x line explicitly, pin the version (npm i @cdklabs/cdk-cicd-wrapper@1.0.0 @cdklabs/cdk-cicd-wrapper-cli@1.0.0). For the 0.x API see the Blueprint (0.x) documentation, and the Migration Guide for the mapping between the two. samples/cdk-cicd-wrapper-example/ is a complete 1.x example. The public API is not frozen and may change.

Welcome to the CDK CI/CD Wrapper

The CDK CI/CD Wrapper gives you an easy way to deliver your CDK applications like a pro. This repository contains all the tools to build, deliver and test any CDK Applications through multiple stages, and AWS accounts to have high level of quality and confidence.

Project Structure

This repository is organized as a monorepo containing multiple packages and tools that work together to provide a comprehensive CI/CD solution:

Core Packages

packages/@cdklabs/cdk-cicd-wrapper - CDK constructs library (jsii — published to npm, PyPI, Maven and NuGet), containing:
- Config authoring - the cicd.config.ts surface: defineCICD, Repository, AppConfig
- Engines - what renders the pipeline: CodePipelineEngine, CdkPipelinesEngine, GitHubActionsEngine
- Runtime injection - CdkCicd.attach for explicit opt-in, plus the preload that cdk-cicd exec uses to wrap a plain CDK app at synth time
- Support resources - SupportResources (lazily provisioned), VPC networking for the pipeline's own CodeBuild projects, log retention, and the default-on security-hardening aspects
packages/@cdklabs/cdk-cicd-wrapper-cli - the cdk-cicd CLI: deploy-ci, exec, synth, check and migrate, plus validate, license, security-scan and check-dependencies

Additional Components

mcp-servers/debugger-mcp/ - MCP (Model Context Protocol) server for AI-powered debugging assistance
samples/ - Example projects demonstrating CDK CI/CD Wrapper usage
- cdk-cicd-wrapper-example/ - TypeScript CDK example
- cdk-python-example/ - Python CDK example
docs/ - Documentation source files and build scripts
projenrc/ - Projen configuration files for managing project structure

Development Workflow

The project uses:

Projen for project management and code generation
Yarn workspaces for monorepo dependency management
Jest for testing across all packages
ESLint + Prettier for code formatting and linting
Commitlint for conventional commit enforcement

Getting Started

To set up the CI/CD pipeline in your existing AWS CDK project, follow these steps:

1. Installation

Important

As noted above, npm install without a version resolves to the 0.x line (currently 0.4.3; avoid 0.4.0, which is deprecated) — which does not have defineCICD or cdk-cicd exec. To follow the 1.x steps below, pin @1.0.0 explicitly (the command shown), or work from a checkout of this repository starting from samples/cdk-cicd-wrapper-example/.

npm i @cdklabs/cdk-cicd-wrapper@1.0.0 @cdklabs/cdk-cicd-wrapper-cli@1.0.0

2. Describe the pipeline in `cicd.config.ts`

Create cicd.config.ts next to your cdk.json. This is the only file the wrapper needs:

import { defineCICD, Repository } from '@cdklabs/cdk-cicd-wrapper';

export default defineCICD({
  application: 'my-project',
  repository: Repository.codecommit('my-project'), // or Repository.s3(...), or Repository.codestarConnection(...) for GitHub
  // 'dev' auto-approves (inner loop); 'prod' is gated by a manual approval by default.
  stages: ['dev', { name: 'prod', env: { account: '111111111111', region: 'eu-west-1' } }],
});

3. Point `cdk.json` at `cdk-cicd exec`

There is no wrapper code in your app. Your bin/ entry point stays exactly what cdk init produced; cdk.json's app command is what wraps it:

{
  "app": "npx cdk-cicd exec bin/my-project.ts"
}

cdk-cicd exec resolves the active stage's config, exports its account/region so a stock env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION } resolves correctly, and runs your entry file under a preload that applies the wrapper's runtime hooks (tagging, default security aspects). Add application stacks to the plain App as you normally would — no provider registry, no wrapper imports:

// bin/my-project.ts — ordinary CDK
import * as cdk from 'aws-cdk-lib';
import { MyStack } from '../lib/my-stack';

const app = new cdk.App();
new MyStack(app, 'my-project', {
  env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION },
});

Optional: use the stageStackName helper to control the CloudFormation stack name per stage (my-project-dev/my-project-prod). Migrating from a previous major? Matching the old stack name is what makes the migration an in-place update instead of a resource replacement — see the Migration Guide.

samples/cdk-cicd-wrapper-example/ is this exact shape as a working project. For a non-Node app entry (for example Python), the preload cannot attach, so use the explicit CdkCicd.attach(app) call instead.

Note: Refer to the Getting Started guide for the full stage shape, repository sources, and CI configuration.

4. Optional Scripts Configuration

By default the pipeline's build step runs npx cdk-cicd check, which covers validate (lock-file integrity), audit (dependency CVEs), license (open-source license checking) and security (Bandit/Semgrep/ShellCheck) — each skipped rather than failed when your project has no baseline for it yet. You do not need to define any scripts to get started.

Setting ci.steps in cicd.config.ts replaces that default rather than adding to it, so include check explicitly if you still want those checks alongside your own build/test. If you would rather drive the same checks from package.json, add the definitions below:

4.1. Adding validate script

jq --arg key "validate" --arg val "cdk-cicd validate" '.scripts[$key] = $val' package.json | jq . > package.json.tmp; mv package.json.tmp package.json;
jq --arg key "validate:fix" --arg val "cdk-cicd validate --fix" '.scripts[$key] = $val' package.json | jq . > package.json.tmp; mv package.json.tmp package.json;

4.2. Adding lint script

We recommend using eslint and you can initialize it:

npm init @eslint/config

jq --arg key "lint" --arg val "eslint . --ext .ts --max-warnings 0" '.scripts[$key] = $val' package.json | jq . > package.json.tmp; mv package.json.tmp package.json;
jq --arg key "lint:fix" --arg val "eslint . --ext .ts --fix" '.scripts[$key] = $val' package.json | jq . > package.json.tmp; mv package.json.tmp package.json;

4.3. Adding audit scripts

npm install --save -D concurrently
jq --arg key "audit" --arg val "concurrently 'npm:audit:*(\!fix)'" '.scripts[$key] = $val' package.json | jq . > package.json.tmp; mv package.json.tmp package.json;
jq --arg key "audit:deps:nodejs" --arg val "cdk-cicd check-dependencies --npm" '.scripts[$key] = $val' package.json | jq . > package.json.tmp; mv package.json.tmp package.json;
jq --arg key "audit:deps:python" --arg val "cdk-cicd check-dependencies --python" '.scripts[$key] = $val' package.json | jq . > package.json.tmp; mv package.json.tmp package.json;
jq --arg key "audit:deps:security" --arg val "cdk-cicd security-scan --bandit --semgrep --shellcheck" '.scripts[$key] = $val' package.json | jq . > package.json.tmp; mv package.json.tmp package.json;
jq --arg key "audit:license" --arg val "npm run license" '.scripts[$key] = $val' package.json | jq . > package.json.tmp; mv package.json.tmp package.json;
jq --arg key "audit:fix:license" --arg val "npm run license:fix" '.scripts[$key] = $val' package.json | jq . > package.json.tmp; mv package.json.tmp package.json;
jq --arg key "license" --arg val "cdk-cicd license" '.scripts[$key] = $val' package.json | jq . > package.json.tmp; mv package.json.tmp package.json;
jq --arg key "license:fix" --arg val "cdk-cicd license --fix" '.scripts[$key] = $val' package.json | jq . > package.json.tmp; mv package.json.tmp package.json;

Example package.json scripts section:

{
  ...
  "scripts": {
    "validate": "cdk-cicd validate",
    "validate:fix": "cdk-cicd validate --fix",
    "audit": "npx concurrently 'npm:audit:*(!fix)'",
    "audit:deps:nodejs": "cdk-cicd check-dependencies --npm",
    "audit:deps:python": "cdk-cicd check-dependencies --python",
    "audit:scan:security": "cdk-cicd security-scan --bandit --semgrep --shellcheck --ci",
    "audit:license": "npm run license",
    "audit:fix:license": "npm run license:fix",
    "license": "cdk-cicd license",
    "license:fix": "cdk-cicd license --fix",
    "lint": "eslint . --ext .ts --max-warnings 0",
    "lint:fix": "eslint . --ext .ts --fix",
    "test": "jest"
    ...
  }
  ...
}

Note: If you are using eslint for linting, ensure that the configuration files are present or generate them with npm init @eslint/config.

5. Pre-deployment Validation

Before deploying, run the following commands to ensure your project is ready:

npm run validate:fix
npm run audit:fix:license

npm run validate:fix will create the required package-verification.json file for you.
npm run audit:fix:license will generate a valid Notice file for you.

6. Bootstrap and deploy the CI/CD Pipeline

Bootstrap every account/region a stage targets, trusting the account the pipeline itself runs in:

npx cdk bootstrap aws://<STAGE_ACCOUNT>/<STAGE_REGION> --trust <PIPELINE_ACCOUNT> \
  --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess

Then, from the account and region the pipeline should run in:

npx cdk-cicd deploy-ci

This provisions the pipeline from cicd.config.ts alone — nothing else needs to exist yet. From there the pipeline self-updates from cicd.config.ts on every run, so deploy-ci is a one-time manual command (and again only if you need to recover a deleted pipeline stack).

What the pipeline does

Source → Build (npm ci, then your ci.steps or the default npx cdk-cicd check, then cdk synth with CDK Nag) → self-update → one deploy action per configured stage, in order, each gated by a manual approval except the inner-loop stage names dev and res (auto-approved by default), unless you set manualApproval explicitly. Autopilot reserves no stage names — dev/res are simply the two that default to auto-approve; every other name is gated.

Supporting resources — the encryption key, VPC networking for the pipeline's own CodeBuild projects, a compliance bucket — are lazily provisioned, so a pipeline only pays for what its configuration actually references.

Note: Check the networking documentation for VPC configurations, and the Migration Guide if you are coming from the previous major, where the pipeline was assembled from a set of named stacks in your own bin/.

Choosing an engine

The engine field in cicd.config.ts selects how the pipeline is rendered. There are three, and the default suits most projects:

EngineType.CODEPIPELINE (default) — a lightweight, flat AWS CodePipeline. Deploy stages re-invoke your app per stage, so bin/ stays a plain single-stage app. Smallest footprint, and the only engine that supports container mode.
EngineType.CDK_PIPELINES — the Blueprint-compatible self-mutating pipeline built on aws-cdk-lib/pipelines (Source → Synth → Assets → one wave per stage). Choose it when you want a pipeline shaped like a Blueprint (0.x) one, e.g. to keep a migration's topology familiar.
EngineType.GITHUB_ACTIONS — renders a GitHub Actions workflow instead of an AWS-hosted pipeline. Requires repository: Repository.github(...) and a githubActions config block.

import { defineCICD, Repository, EngineType } from '@cdklabs/cdk-cicd-wrapper';

export default defineCICD({
  application: 'my-app',
  repository: Repository.github('my-org/my-app'),
  engine: EngineType.CDK_PIPELINES, // omit for the default CODEPIPELINE
  stages: ['dev', 'prod'],
});

See the Configuration Reference for the full engine and field surface.

Visit our documentation to learn more.

Use cases

The CDK CI/CD Wrapper is the next step on road to standardize and simplify the multi-stage CI/CD process that the successful aws-cdk-cicd-boot-sample started. Thus the use cases for the CDK CI/CD Wrapper are the same as for the aws-cdk-cicd-boot-sample.

Multi staged CI/CD pipeline for IaC projects

On top of that the CDK CI/CD Wrapper has arbitrary scripts that can be leveraged in any projects involving TypeScript, and/or Python.

CI/CD execution by AWS CodePipeline in VPC, Private VPC with NAT Gateway, or even through an HTTP Proxy
Security scanning on dependencies and on your project codebase as well
License management over NPM and Python dependencies
Support for private NPM registry to safely store your libraries
Customizable CI/CD pipeline to attach to your CDK applications which comes with built-in dependency injection
Workbench deployment feature which allows you to develop and experiment your solutions before it is introduced in the delivery pipeline, e.g: deploy and test one or multiple CDK stacks isolated from the ones deployed by the CI/CD pipeline (0.x only — 1.x has no pipeline equivalent; use a direct cdk deploy, see MIGRATION.md)

Intended usage

You should not fork this repository and expect to reproduce the same in your AWS Accounts, this repository is only used for preparing, testing and shipping all the packages used by the CDK CI/CD Wrapper. Using the CDK CI/CD Wrapper gives you the following benefits:

✅ FOSS (Free and open-source software) scanning – built-in checks against a pre-defined adjustable list of licenses
✅ Workbench – isolated test environment for developers which enables parallel testing in the same AWS Account without collisions (0.x only; 1.x has no pipeline equivalent — use a direct cdk deploy, see MIGRATION.md)
✅ Automated security scanners – enabled by default bandit, shellcheck, npm audit, pip audit, etc)
✅ AWS CDK Language agnostic – support for TypeScript and Python, on the works to fully support Java / C# / Go
✅ Built for many project types - facilitating MLOps usecase, Web App development (UIs), GenAI usecases

MCP Debugger Server

The CDK CI/CD Wrapper includes a specialized MCP (Model Context Protocol) Debugger Server that provides AI-powered debugging assistance for your CDK CI/CD Wrapper applications. This debugger server integrates seamlessly with MCP-compatible AI tools to help diagnose and resolve common configuration and deployment issues.

Compatible MCP Clients

The debugger server works with any MCP-compatible client, including:

Amazon Q CLI - Amazon's AI-powered command-line assistant (Installation Guide)
Cline - The Collaborative AI Coder. Experience an AI development partner that amplifies your engineering capabilities
Any other MCP-compatible client - The server follows the standard MCP protocol specification

Key Features

The MCP Debugger Server offers six specialized debugging tools:

🔧 Comprehensive Configuration Analysis - Validates all environment variables and configuration files to ensure proper setup
📊 Stage Definition Verification - Checks that deployment stages are correctly defined with proper account mappings
🔗 Git Provider Configuration - Validates GitHub/CodeCommit setup and tests connectivity
⚙️ CI/CD Configuration Analysis - Analyzes CodePipeline or GitHub Actions configuration for proper setup
🔌 Plugin Security Analysis - Identifies custom plugins and highlights potential security implications
🌐 VPC Configuration Validation - Ensures VPC and networking configurations are properly set up

Benefits

AI-Powered Troubleshooting - Work with AI assistants to quickly identify and resolve configuration issues
Comprehensive Project Validation - Run complete health checks on your CDK CI/CD Wrapper projects
Proactive Issue Detection - Catch configuration problems before they cause deployment failures
Security Analysis - Identify potentially unsafe plugin configurations and security risks
Environment Validation - Ensure all required environment variables and AWS credentials are properly configured

Getting Started with the Debugger

The MCP Debugger Server is located under mcp-servers/debugger-mcp/ and can be used with any MCP-compatible clients as mentioned above. For detailed setup instructions, configuration examples, and usage guides, see the MCP Debugger README.

Security

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.

Community

The CDK CI/CD Wrapper community can be found within the #cdk-cicd-wrapper channel in the cdk.dev community Slack workspace.

Contributors

Thanks goes to these wonderful people (emoji key):

_{Gezim Musliaj}
💻

_{Milan Gyalai @ AWS}
💻

_{Vladimir Dainovski}
💻

_{Fabrizio Manfredi F.}
💻

Name		Name	Last commit message	Last commit date
.claude		.claude
.github		.github
.husky		.husky
.projen		.projen
.tmp		.tmp
docs		docs
mcp-servers/debugger-mcp		mcp-servers/debugger-mcp
packages/@cdklabs		packages/@cdklabs
projenrc		projenrc
samples		samples
test		test
tools		tools
.aislopignore		.aislopignore
.all-contributorsrc		.all-contributorsrc
.eslintrc.json		.eslintrc.json
.gitattributes		.gitattributes
.gitignore		.gitignore
.mergify.yml		.mergify.yml
.npmignore		.npmignore
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
.projenrc.ts		.projenrc.ts
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONFIGVARS.md		CONFIGVARS.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MIGRATION.md		MIGRATION.md
NOTICE		NOTICE
OSS_License_Summary.csv		OSS_License_Summary.csv
README.md		README.md
SECURITY.md		SECURITY.md
Taskfile.codeartifact.yml		Taskfile.codeartifact.yml
Taskfile.sample-app.yml		Taskfile.sample-app.yml
Taskfile.yml		Taskfile.yml
bandit.yaml		bandit.yaml
devbox.json		devbox.json
devbox.lock		devbox.lock
findings.json		findings.json
licensecheck.json		licensecheck.json
package-verification.json		package-verification.json
package.json		package.json
task.md		task.md
tsconfig.dev.json		tsconfig.dev.json
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

Navigation Menu

Uh oh!

Repository files navigation

CDK CI/CD Wrapper

Welcome to the CDK CI/CD Wrapper

Project Structure

Core Packages

Additional Components

Development Workflow

Getting Started

1. Installation

2. Describe the pipeline in `cicd.config.ts`

3. Point `cdk.json` at `cdk-cicd exec`

4. Optional Scripts Configuration

4.1. Adding validate script

4.2. Adding lint script

4.3. Adding audit scripts

5. Pre-deployment Validation

6. Bootstrap and deploy the CI/CD Pipeline

What the pipeline does

Choosing an engine

Use cases

Intended usage

MCP Debugger Server

Compatible MCP Clients

Key Features

Benefits

Getting Started with the Debugger

Security

License

Community

Contributors

About

Releases

Used by

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

CDK CI/CD Wrapper

Welcome to the CDK CI/CD Wrapper

Project Structure

Core Packages

Additional Components

Development Workflow

Getting Started

1. Installation

2. Describe the pipeline in cicd.config.ts

3. Point cdk.json at cdk-cicd exec

4. Optional Scripts Configuration

4.1. Adding validate script

4.2. Adding lint script

4.3. Adding audit scripts

5. Pre-deployment Validation

6. Bootstrap and deploy the CI/CD Pipeline

What the pipeline does

Choosing an engine

Use cases

Intended usage

MCP Debugger Server

Compatible MCP Clients

Key Features

Benefits

Getting Started with the Debugger

Security

License

Community

Contributors

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Used by

Contributors

Languages

2. Describe the pipeline in `cicd.config.ts`

3. Point `cdk.json` at `cdk-cicd exec`