Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

CDK Pipelines for GitHub Workflows


NOTICE: this library is still not published to package managers. Stay tuned.

Deploy CDK applications through GitHub workflows.


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 { ShellStep } from 'aws-cdk-lib/pipelines';
import { GithubWorkflow } from 'cdk-pipelines-github';

const app = new App();

const pipeline = new GithubWorkflow(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 }));


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.


  • 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 and AWS_SECRET_ACCESS_KEY).


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
cd cdk-pipelines-github

Now, create a new GitHub repository and clone it as well:

cd ~/projects
git clone

You'll need to set up AWS credentials in your environment:

export AWS_ACCESS_KEY_ID=xxxx

Bootstrap your environments:

npx cdk bootstrap aws://ACCOUNTID/us-east-1
npx cdk bootstrap aws://ACCOUNTID/eu-west-2

Now, run the script when your working directory is the new repository:

cd ~/projects/my-test-repository

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
  • Anti-tamper check for CI runs (synth should fail if CI=1 and the workflow has changed)
  • Revise Documentation


See CONTRIBUTING for more information.


This project is licensed under the Apache-2.0 License.