CDK Pipelines for GitHub Workflows
NOTICE: this library is still not published to package managers. Stay tuned.
Deploy CDK applications through GitHub workflows.
Usage
Assuming you have a
Stage
called MyStage
that includes CDK stacks for your app and you want to deploy it
to two AWS environments (BETA_ENV
and PROD_ENV
):
import { Pipeline } from 'cdk-pipelines-github';
const app = new App();
const pipeline = new Pipeline(app, 'Pipeline', {
synth: new ShellStep('Build', {
commands: [
'yarn install',
'yarn build',
],
}),
workflowPath: '.github/workflows/deploy.yml',
});
pipeline.addStage(new MyStage(this, 'Beta', { env: BETA_ENV }));
pipeline.addStage(new MyStage(this, 'Prod', { env: PROD_ENV }));
app.synth();
When you run cdk synth
, a deploy.yml
workflow will be created under
.github/workflows
in your repo. This workflow will deploy your application
based on the definition of the pipeline. In this case, it will the two stages in
sequence, and within each stage, it will deploy all the stacks according to
their dependency order and maximum parallelism. If you app uses assets, assets
will be published to the relevant destination environment.
The Pipeline
class from cdk-pipelines-github
is derived from the base CDK
Pipelines class, so most features should be supported out of the box. See the
CDK Pipelines
documentation for more details.
NOTES:
- Environments must be bootstrapped separately using
cdk bootstrap
. See CDK Environment Bootstrapping for details. - The workflow expects the GitHub repository to include secrets with AWS
credentials (
AWS_ACCESS_KEY_ID
andAWS_SECRET_ACCESS_KEY
).
Example
You can find an example usage in test/example-app.ts which includes a simple CDK app and a pipeline.
You can find a repository that uses this example here: eladb/test-app-cdkpipeline.
To run the example, clone this repository and install dependencies:
cd ~/projects # or some other playground space
git clone https://github.com/cdklabs/cdk-pipelines-github
cd cdk-pipelines-github
yarn
Now, create a new GitHub repository and clone it as well:
cd ~/projects
git clone https://github.com/myaccount/my-test-repository
You'll need to set up AWS credentials in your environment:
export AWS_ACCESS_KEY_ID=xxxx
export AWS_SECRET_ACCESS_KEY=xxxxx
Bootstrap your environments:
export CDK_NEW_BOOTSTRAP=1
npx cdk bootstrap aws://ACCOUNTID/us-east-1
npx cdk bootstrap aws://ACCOUNTID/eu-west-2
Now, run the manual-test.sh
script when your working directory is the new repository:
cd ~/projects/my-test-repository
~/projects/cdk-piplines/github/test/manual-test.sh
This will produce a cdk.out
directory and a .github/workflows/deploy.yml
file.
Commit and push these files to your repo and you should see the deployment
workflow in action. Make sure your GitHub repository has AWS_ACCESS_KEY_ID
and
AWS_SECRET_ACCESS_KEY
secrets that can access the same account that you
synthesized against.
Not supported yet
This is work in progress. The following features are still not supported:
- Credentials and roles (document permissions required, etc)
- Support Docker image assets
- Support Pre/post steps
- Support CFN output bindings
- Anti-tamper check for CI runs (
synth
should fail ifCI=1
and the workflow has changed) - Revise Documentation
Contributing
See CONTRIBUTING for more information.
License
This project is licensed under the Apache-2.0 License.