jjrawlins-cdk-deploy-pr-github-action 0.0.34

A projen construct that generates GitHub Actions workflows for CDK deployments with GitHub Environments, parallel stages, versioned assemblies, and manual rollback.

@jjrawlins/cdk-deploy-pr-github-action

A projen construct that generates GitHub Actions workflows for AWS CDK deployments.

Features

• Automated deploy pipeline (deploy.yml) — synth, publish assets, and deploy on push to main
• Manual dispatch workflow (deploy-dispatch.yml) — deploy any previously published version to any environment
• Versioned cloud assemblies — publishes cdk.out to GitHub Packages with auto-incrementing versions
• GitHub Releases — each deploy creates a git tag and GitHub Release tied to the assembly version
• Multi-stage deployments — parallel or sequential stages with dependsOn ordering
• GitHub Environments — per-stage environment protection rules, secrets scoping, and deployment approvals
• Manual approval stages — exclude stages from auto-deploy, only deployable via dispatch
• Per-stage IAM role overrides — cross-account deployments with per-stage OIDC roles
• Concurrency groups — prevents concurrent deployments to the same stage
• Rollback support — redeploy any previous assembly version via the dispatch workflow

Installation

npm install @jjrawlins/cdk-deploy-pr-github-action

Also available on PyPI, NuGet, and Go.

Usage

In your .projenrc.ts:

import { CdkDeployPipeline } from '@jjrawlins/cdk-deploy-pr-github-action';

new CdkDeployPipeline(project, {
  stackPrefix: 'MyApp',
  pkgNamespace: '@my-org',
  iamRoleArn: 'arn:aws:iam::111111111111:role/GitHubActionsOidcRole',
  iamRoleRegion: 'us-east-1',
  stages: [
    {
      name: 'dev',
      env: { account: '222222222222', region: 'us-east-1' },
      environment: 'development',
    },
    {
      name: 'staging',
      env: { account: '333333333333', region: 'us-east-1' },
      environment: 'staging',
      dependsOn: ['dev'],
    },
    {
      name: 'prod',
      env: { account: '444444444444', region: 'us-east-1' },
      environment: 'production',
      dependsOn: ['staging'],
      manualApproval: true, // Only deployable via dispatch
    },
  ],
});

Run npx projen to generate the workflow files.

Generated Workflows

deploy.yml

Triggered on push to main. Jobs:

1. synth — checks out code, installs dependencies, runs cdk synth, uploads cloud assembly artifact
2. publish-assets — publishes Lambda/container assets to AWS, versions and publishes the cloud assembly to GitHub Packages, creates a git tag and GitHub Release
3. deploy-{stage} — one job per non-manual stage, deploys stacks using the cloud assembly artifact

deploy-dispatch.yml

Triggered manually via workflow_dispatch. Inputs:

• environment — target environment (dropdown of configured stages)
• version — assembly version to deploy (e.g., 0.0.4)

Downloads the specified assembly version from GitHub Packages and deploys it. This enables:

• Deploying to manualApproval stages (e.g., production)
• Rolling back to any previous version
• Ad-hoc deployments outside the normal CI/CD flow

Options

CdkDeployPipelineOptions

Option	Type	Default	Description
pkgNamespace	string	required	npm scope for assembly packages (e.g., @my-org)
stackPrefix	string	required	Stack name prefix (e.g., MyApp -> MyApp-dev)
iamRoleArn	string	required	Default OIDC role ARN for AWS credential assumption
stages	DeployStageOptions[]	required	Deployment stages
iamRoleRegion	string	us-east-1	Default AWS region for OIDC credential assumption
nodeVersion	string	24.x	Node.js version for workflow runners
cdkCommand	string	npx cdk	CDK CLI command prefix
installCommand	string	yarn install --check-files --frozen-lockfile	Package install command
manualDeployment	boolean	true	Generate the dispatch workflow
useGithubPackagesForAssembly	boolean	true	Publish cloud assembly to GitHub Packages
branchName	string	main	Branch that triggers deployments
workingDirectory	string	—	Subdirectory where the CDK app lives (e.g., infra). Sets defaults.run.working-directory on all jobs and adjusts artifact paths.
preGitHubSteps	any	—	Steps to run before deploy (after install/download, before AWS creds). Static array or factory ({ stage, workingDirectory }) => steps[]. Applied to deploy jobs only.
postGitHubSteps	any	—	Steps to run after deploy. Static array or factory ({ stage, workingDirectory }) => steps[]. Applied to deploy jobs only.

DeployStageOptions

Option	Type	Default	Description
name	string	required	Stage name (used in job IDs and stack names)
env	{ account, region }	required	AWS target environment
environment	string	stage name	GitHub Environment name
iamRoleArn	string	pipeline default	Override OIDC role for this stage
iamRoleRegion	string	pipeline default	Override AWS region for this stage
dependsOn	string[]	[]	Stages that must complete first
stacks	string[]	['{stackPrefix}-{name}']	CDK stack names to deploy
manualApproval	boolean	false	Exclude from auto-deploy, dispatch only

Examples

Parallel stages

Stages without dependsOn run in parallel after asset publishing:

stages: [
  { name: 'us-east-1', env: usEast1Env },
  { name: 'eu-west-1', env: euWest1Env },
]

Cross-account with per-stage roles

stages: [
  {
    name: 'dev',
    env: { account: '222222222222', region: 'us-east-1' },
    iamRoleArn: 'arn:aws:iam::222222222222:role/DevDeployRole',
  },
  {
    name: 'prod',
    env: { account: '333333333333', region: 'us-east-1' },
    iamRoleArn: 'arn:aws:iam::333333333333:role/ProdDeployRole',
    manualApproval: true,
  },
]

Rolling back

Each deploy creates a GitHub Release with the assembly version. To roll back:

gh workflow run deploy-dispatch.yml -f environment=production -f version=0.0.3

Monorepo support

If your CDK app lives in a subdirectory, use the workingDirectory option:

new CdkDeployPipeline(project, {
  stackPrefix: 'MyApp',
  pkgNamespace: '@my-org',
  iamRoleArn: 'arn:aws:iam::111111111111:role/GitHubActionsOidcRole',
  workingDirectory: 'infra',
  stages: [
    { name: 'dev', env: devEnv, environment: 'development' },
    { name: 'prod', env: prodEnv, environment: 'production', manualApproval: true },
  ],
});

This sets defaults.run.working-directory: infra on all workflow jobs and adjusts artifact upload/download paths to infra/cdk.out/.

Pre/post workflow steps

Use preGitHubSteps and postGitHubSteps to run custom steps before and after deployments. These are applied to deploy jobs only (not synth or publish-assets). Useful for building source code, sending Slack notifications, or running health checks.

new CdkDeployPipeline(project, {
  stackPrefix: 'MyApp',
  pkgNamespace: '@my-org',
  iamRoleArn: 'arn:aws:iam::111111111111:role/GitHubActionsOidcRole',
  workingDirectory: 'infra',
  stages: [
    { name: 'dev', env: devEnv, environment: 'development' },
  ],
  preGitHubSteps: ({ stage, workingDirectory }) => [
    // Build at project root (overrides working-directory default)
    { name: 'Build app', run: 'npm run build', 'working-directory': '.' },
  ],
  postGitHubSteps: ({ stage }) => [
    { name: 'Notify Slack', uses: 'slackapi/slack-github-action@v2', with: { /* ... */ } },
  ],
});

Pre/post steps are also passed through to deploy-dispatch.yml so dispatch deployments get the same hooks.

Deploy jobs include step IDs creds (AWS Credentials) and deploy (Deploy step) that post-steps can reference via ${{ steps.deploy.outcome }}.

Note: When workingDirectory is set, all run: steps inherit that directory by default. To run a step at the repository root, add working-directory: '.' to that step.

Prerequisites

• AWS OIDC identity provider configured for GitHub Actions
• IAM role with trust policy for GitHub Actions OIDC
• GitHub Environments configured for deployment protection rules (optional)

License

Apache-2.0