cdk-pipelines-github 0.0.92

GitHub Workflows support for CDK Pipelines

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 { 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 }));

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 and AWS_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)
• Anti-tamper check for CI runs (synth should fail if CI=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.