Package: opinionated-ci-pipeline
Opinionated CDK CI PipelineCI/CD utilizingCDK Pipelines.See theannouncement blog postfor examples and architecture diagrams.Features:pipeline deploying application from the default branch
to multiple environments on multiple accounts,feature branch deployments to ephemeral environments,development environments deployments from the local CLI,build status notifications to repository commits,build failures notifications to SNS.Currently supported source repositories are GitHub and Bitbucket.Table of contentsTable of contentsUsage1. Install2. Set context parameters3. CreateCDKApplication4. Create repository access tokenGitHubBitbucket5. Bootstrap the CDK6. Deploy the CI StackDeploy development environmentParametersNotifications and alarmsHow toRun unit tests during buildEnable DockerLibrary developmentUsageTo set up, you need to complete the following steps:Install the library in your project.Specify context parameters.CreateCDKApplicationwith build process configuration.Create repository access token.Bootstrap the CDK on the AWS account(s).Deploy the CI.At the end, you will have CI pipeline in place,
and be able to deploy your own custom environment from the CLI as well.1. InstallFor Node.js:npminstall-Dopinionated-ci-pipelineFor Python:pipinstallopinionated-ci-pipeline2. Set context parametersAdd project name and environments config in thecdk.jsonascontextparameters.
Each environment must haveaccountandregionprovided.{"app":"...","context":{"projectName":"myproject","environments":{"default":{"account":"111111111111","region":"us-east-1"},"prod":{"account":"222222222222","region":"us-east-1"}}}}The project name will be used as a prefix for the deployed CI Stack name.Environment names should match environments provided later
in theCDKApplicationconfiguration.The optionaldefaultenvironment configuration is used as a fallback.The CI pipeline itself is deployed to thecienvironment,
with a fallback to thedefaultenvironment as well.3. CreateCDKApplicationIn the CDK entrypoint script referenced by thecdk.jsonappfield,
replace the content with an instance ofCDKApplication:#!/usr/bin/env nodeimport'source-map-support/register';import{ExampleStack}from'../lib/exampleStack';import{CDKApplication}from'opinionated-ci-pipeline';newCDKApplication({stacks:{create:(scope,projectName,envName)=>{newExampleStack(scope,'ExampleStack',{stackName:`${projectName}-${envName}-ExampleStack`});},},repository:{host:'github',name:'organization/repository',},packageManager:'npm',pipeline:[{environment:'test',post:['echo "do integration tests here"',],},{environment:'prod',},],});This configures the application with one Stack
and a pipeline deploying to an environmenttest,
running integration tests, and deploying to environmentprod.Thetestandprodenvironments will be deployed
from the branchmain(by default).
All other branches will be deployed to separate environments.
Those feature-branch environments will be destroyed after the branch is removed.To allow deployment of multiple environments,
the Stack(s) name must include the environment name.4. Create repository access tokenAn access to the source repository is required
to fetch code and send build status notifications.Once access token is created, save it in SSM Parameter Store
as aSecureStringunder the path/{projectName}/ci/repositoryAccessToken.See instructions below on how to create the token
for each supported repository host.GitHubCreatea fine-grained personal access tokenwith read-only access forContentsread and write access forCommit statusesandWebhooks.BitbucketIn Bitbucket, go to your repository.
Open Settings → Access tokens.
There, create a new Repository Access Token
withrepository:writeandwebhookscopes.5. Bootstrap the CDKBootstrap the CDKon the account holding the CI pipeline
and all other accounts the pipeline will be deploying to.When bootstrapping other accounts, add the--trustparameter
with the account ID of the account holding the pipeline.6. Deploy the CI StackRun:cdkdeploy-cci=trueDeploy development environmentRun:cdkdeploy-cenv=MYENV--allto deploy arbitrary environments.ParametersNameTypeDescriptionstacksobjectAn object with a create() method to create Stacks for the application.The same Stacks will be deployed with main pipeline, feature-branch builds, and local deployments.packageManagernpm | pnpmPackage manager used in the repository.If provided, theinstallcommand will be set to install dependencies using given package manager.commandsobjectCommands executed to build and deploy the application.The following commands are set by default:installsynthPipelinedeployEnvironmentdestroyEnvironmentIf you override theinstallcommand,
either install theaws-cdk@2globally
or modify the other 3 commands to use the localcdkbinary.Commands executed on particular builds:main pipeline:preInstallinstallbuildAndTestsynthPipelinefeature branch environment deployment:preInstallinstallbuildAndTestdeployEnvironmentfeature branch environment destruction:preInstallinstalldestroyEnvironmentcdkOutputDirectorystringThe location where CDK outputs synthetized files.
Corresponds to the CDK PipelinesShellStepProps#primaryOutputDirectory.pipelineobject[]CodePipeline deployment pipeline for the main repository branch.Can contain environments to deploy
and waves that deploy multiple environments in parallel.Each environment and wave can have pre and post commands
that will be executed before and after the environment or wave deployment.codeBuildobjectOverride CodeBuild properties, used for the main pipeline
as well as feature branch ephemeral environments deploys and destroys.codePipelineobjectOverride CodePipeline properties.slackNotificationsobjectConfiguration for Slack notifications.
Requires configuring AWS Chatbot client manually first.Notifications and alarmsStack creates SNS Topics with notifications for
main pipeline failures and feature branch build failures.
Their ARNs are saved in SSM Parameters and outputed by the stack:main pipeline failures:SSM:/{projectName}/ci/pipelineFailuresTopicArnStack exported output:{projectName}-ci-pipelineFailuresTopicArnfeature branch build failures:SSM:/{projectName}/ci/featureBranchBuildFailuresTopicArnStack exported output:{projectName}-ci-featureBranchBuildFailuresTopicArnIf you setup Slack notifications,
you can configure those failure notifications to be sent to Slack.Moreover, if you setup Slack notifications,
an additional SNS Topic will be created
to which you can send CloudWatch Alarms.
It's ARN is provided:SSM:/{projectName}/ci/slackAlarmsTopicArnStack exported output:{projectName}-ci-slackAlarmsTopicArnHow toRun unit tests during buildSet commands in thecommands.buildAndTest:{commands:{buildAndTest:['npm run lint','npm run test',]}}Enable DockerSetcodeBuild.buildEnvironment.privilegedtotrue:{codeBuild:{buildEnvironment:{privileged:true}}}Library developmentProject usesjsiito generate packages for different languages.Install dependencies:npminstallBuild:npmrunbuildInstall and deploy example application:cdexample
pnpminstall
pnpmcdkdeploy-cci=trueMentionsGit repository push to CodeCommit inside Lambda function
based onhttps://msimpson.co.nz/Github-CodeCommit/