Documentation · Changelog · Join the community
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.
To set up the CI/CD pipeline in your existing AWS CDK project, follow these steps:
Install the CDK CI/CD Wrapper pipeline package by running the following command:
npm i @cdklabs/cdk-cicd-wrapper @cdklabs/cdk-cicd-wrapper-cli
Open your entry file, typically located at bin/<your-main-file>.ts
(where your-main-file
is the name of your root project directory).
Include the PipelineBlueprint.builder().synth(app)
statement in your entry file, like so:
import * as cdk from 'aws-cdk-lib';
import { PipelineBlueprint } from '@cdklabs/cdk-cicd-wrapper';
const app = new cdk.App();
PipelineBlueprint.builder().synth(app);
This will deploy the CI/CD pipeline with its default configuration without deploying any stacks into the staging accounts.
Optional: If you want to include additional stacks in the CI/CD pipeline, modify your entry file as follows:
import * as cdk from 'aws-cdk-lib';
import { PipelineBlueprint, GlobalResources } from '@cdklabs/cdk-cicd-wrapper';
const app = new cdk.App();
PipelineBlueprint.builder().addStack({
provide: (context) => {
// Create your stacks here
new YourStack(context.scope, `${context.blueprintProps.applicationName}YourStack`, {
applicationName: context.blueprintProps.applicationName,
stageName: context.stage,
});
new YourOtherStack(context.scope, `${context.blueprintProps.applicationName}YourOtherStack`, {
applicationQualifier: context.blueprintProps.applicationQualifier,
encryptionKey: context.get(GlobalResources.ENCRYPTION)!.kmsKey,
});
}}).synth(app);
Note: Refer to the Developer Guide for more information on the PipelineBlueprint
.
The CDK CI/CD Wrapper expects to have the validate
, lint
, test
, audit
scripts defines. If you are missing any of the npm run
scripts (e.g., ), or want to use the provided CLI tool for one or more actions, you can add the following definitions to your package.json
file:
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;
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
```typescript
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;
{
...
"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
.
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.Deploy all the stacks by running the following command:
npx dotenv-cli -- npm run cdk deploy -- --all --region ${AWS_REGION} --profile $RES_ACCOUNT_AWS_PROFILE --qualifier ${CDK_QUALIFIER}
Once the command finishes, the following CDK Stacks will be deployed into your RES Account:
npx {{ npm_cli }}@latest configure
. Check here for more information on possible configurations.Visit our documentation to learn more.
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.
On top of that the CDK CI/CD Wrapper has arbitrary scripts that can be leveraged in any projects involving TypeScript, and/or Python.
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:
See CONTRIBUTING for more information.
This project is licensed under the Apache-2.0 License.
The CDK CI/CD Wrapper community can be found within the #cdk-cicd-wrapper channel in the cdk.dev community Slack workspace.
Thanks goes to these wonderful people (emoji key):
Gezim Musliaj 💻 |
Milan Gyalai @ AWS 💻 |
Vladimir Dainovski 💻 |
Fabrizio Manfredi F. 💻 |