CDK CI/CD Wrapper
The CDK CI/CD Wrapper is a comprehensive solution that streamlines the delivery of your AWS Cloud Development Kit (CDK) applications. It provides a robust and standardized multi-stage CI/CD pipeline, ensuring high quality and confidence throughout the development and deployment process.
Table of Contents
Introduction
The CDK CI/CD Wrapper builds upon the success of the aws-cdk-cicd-boot-sample and takes it a step further by providing additional tools and features to simplify and standardize the multi-stage CI/CD process for your Infrastructure as Code (IaC) projects.
Features
- Multi-staged CI/CD Pipeline: Seamlessly deploy your CDK applications across multiple stages (e.g., DEV, INT, PROD) and AWS accounts.
- Security Scanning: Perform security scanning on dependencies and codebase, blocking the pipeline in case of CVE findings.
- License Management: Manage licenses for NPM and Python dependencies, ensuring compliance with your organization's policies.
- Private NPM Registry: Securely store and utilize private NPM libraries.
- Customizable Pipeline: Tailor the CI/CD pipeline to your project's specific needs with built-in dependency injection.
- Workbench Deployment: Develop and experiment with your solutions in isolation before introducing them to the delivery pipeline.
- Pre/Post Deploy Hooks: Execute custom scripts before and after deployments in each stage (e.g., unit tests, functional tests, load testing).
- Centralized Compliance Logs: Store compliance logs in pre-configured S3 buckets on a per-stage/environment basis.
- Lambda Layer Support: Build and scan dependencies for Python Lambda Layers.
Getting Started
Prerequisites
Before you begin, ensure that you have the following dependencies installed:
- AWS Account (RES/DEV/INT/PROD)
- macOS or Cloud9 with Ubuntu Server 22.04 LTS Platform in the RES Account
- Bash/ZSH terminal
- Docker version >= 24.0.x
- AWS CLI v2 (installation guide)
- AWS credentials and profiles for each environment in
~/.aws/config(configuration guide) - Node.js >= v18.17._ && NPM >= v10.2._
- jq command-line JSON processor (jq-1.7)
For developing Python Lambdas, you'll also need:
- Python >= 3.11
- Pipenv 2023.* (installation guide)
Installation
-
Clone the CDK CI/CD Wrapper repository:
git clone https://github.com/your-repo/cdk-cicd-wrapper.git cd cdk-cicd-wrapper
-
Install the required dependencies:
npm install
Usage
Defining Stages
The CDK CI/CD Wrapper comes with a default set of stages (DEV, INT, PROD), but you can easily extend or modify these stages to suit your project's needs. Follow the step-by-step guide in the documentation to define your desired stages.
Configuring Stacks
Configure the CDK stacks you want to deploy in each stage. The CDK CI/CD Wrapper allows you to specify which stacks should be deployed in each stage, giving you granular control over your deployment process.
Customizing CI/CD Steps
Tailor the CI/CD pipeline to meet your project's specific requirements. The CDK CI/CD Wrapper provides built-in dependency injection, allowing you to customize the CI/CD steps seamlessly.
Autopilot Deployment Contracts
| Area | Contract |
|---|---|
APP_STAGING |
Valid for direct/local cdk deploy (including local cdk-cicd deploy --from-image) and Repo 1 container-image synthesis. Wrapper-generated deployment pipelines—flat CODEPIPELINE, Repo 2, CDK_PIPELINES, and GITHUB_ACTIONS—reject it. On direct/local paths, custom deploy and CloudFormation execution roles govern application stacks; staging support resources use caller/base credentials. |
Deploy-role ExternalId |
CDK_PIPELINES and GITHUB_ACTIONS reject configured deploy-role ExternalIds rather than silently dropping them. APP_STAGING accepts custom deployment identities but rejects a deploy-role ExternalId because the alpha API does not expose one. |
| CloudFormation execution role | CodeBuild assumes the deployment role; that assumed role passes the configured CloudFormation execution role to CloudFormation. Grant iam:PassRole to the deployment role, not directly to the CodeBuild project role. |
| Custom CodeBuild ECR image | A private ECR environment image must be in the CodeBuild project's Region; flat CodePipeline and CDK Pipelines also require the pipeline account. Repo 2 supports its explicit cross-account image path only after the owner-side repository policy is configured and crossAccountEcrRepositoryPolicyConfigured is acknowledged; the build-image Region rule still applies. |
| GitHub manual approval | Configure required reviewers on each generated GitHub Environment, then set githubActions.environmentProtectionConfigured: true. Referencing an environment in workflow YAML does not configure its protection rules. |
Contributing
Contributions to the CDK CI/CD Wrapper are welcome! If you'd like to contribute, please follow the guidelines outlined in the CONTRIBUTING.md file.
License
This project is licensed under the Apache 2.0 License.
1 maintainer
Metadata
1 maintainer
Release files for cdklabs.cdk-cicd-wrapper 2.3.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| cdklabs_cdk_cicd_wrapper-2.3.3.tar.gz | 941.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| cdklabs_cdk_cicd_wrapper-2.3.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.9 MB
Release files / cdklabs_cdk_cicd_wrapper-2.3.3.tar.gz
| Download URL | cdklabs_cdk_cicd_wrapper-2.3.3.tar.gz |
|---|---|
| Size | 941.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dc49586fd32afdc00185e4c93c0656adf2f143d24a9b0f27bb4e346be245c8af
|
|
BLAKE2b-256 checksum How to use checksums |
662658961741c9a1ac22d2b9b329d7f977e6d7c36896c0b21db62a8210a4f237
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.14.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / cdklabs_cdk_cicd_wrapper-2.3.3-py3-none-any.whl
| Download URL | cdklabs_cdk_cicd_wrapper-2.3.3-py3-none-any.whl |
|---|---|
| Size | 939.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c63e8f42fb9e081c95afaf48fa97efc44d8fa918d58e68c5bc24a9bd1528325e
|
|
BLAKE2b-256 checksum How to use checksums |
f1e7f082b4c4a60be2fd8ea1f3adccb88d674b30b009309b1cb6ba570c69789c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.14.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency log
