Helpers

Helper utilities for naming, branch handling, Projen task generation, and CI/CD workflow creation.

env-helper.ts

Source: src/bin/env-helper.ts

Exported types and constants

  • type Environment = 'sandbox' | 'development' | 'test' | 'staging' | 'production'
  • const SUPPORTED_CDK_ACTIONS = ['synth','diff','deploy','destroy','ls'] as const
  • interface EnvironmentConfig { accountId: string; enableBranchDeploy: boolean }

getTaskName

Returns task names like development:synth, test:deploy:all, or staging:branch:destroy:stack. Accepts the environment, CDK action, and options for branch-aware naming plus all/stack variants.

addCdkActionTask

Adds npm tasks to a Projen AwsCdkTypeScriptApp for all supported CDK actions. For deploy|destroy|diff it creates both :all and :stack variants; :stack forwards args. Example tasks generated: test:synth, test:deploy:all, test:deploy:stack.

extractCleanedBranchName

Derives a safe branch name from GIT_BRANCH_REF, excluding main, develop, development, and tags like v1.2.3. Cleans to alphanumeric and hyphens, trims trailing hyphens, and caps at 25 characters.

createEnvResourceName

Uses GIT_BRANCH_REF (if present and not main) or ENVIRONMENT to suffix names, max 64 characters, and throws if GIT_BRANCH_REF resolves to main to avoid accidental branch-based production deploys.

Usage with Projen

// .projenrc.ts
import { addCdkActionTask } from './src/bin/env-helper';

addCdkActionTask(project, {
  CDK_DEFAULT_ACCOUNT: '111111111111',
  CDK_DEFAULT_REGION: 'eu-west-1',
  ENVIRONMENT: 'test',
  GITHUB_DEPLOY_ROLE: 'GitHubActionsServiceRole',
});
// Generates npm scripts like "test:synth", "test:deploy:all", etc.

Using the naming helper in code

import { createEnvResourceName } from '../bin/env-helper';
new Stack(app, createEnvResourceName('StarterStack'), { env });

cicd-helper.ts

Source: src/bin/cicd-helper.ts

createCdkDeploymentWorkflows

  • Always creates a regular env deployment workflow (e.g., cdk-deploy-test).
  • If enableBranchDeploy is true, also creates cdk-deploy-<env>-branch and cdk-destroy-<env>-branch workflows.
  • Chains env workflows using workflow_run when orderedEnvs is provided.
  • Configures OIDC credentials with aws-actions/configure-aws-credentials@v4 and installs deps via npm ci.
  • Runs npm tasks generated by addCdkActionTask, e.g., npm run test:synth.

Trigger behavior

  • First env in orderedEnvs: triggers on push to main.
  • Subsequent envs: trigger on completion of the previous env’s workflow.
  • Branch workflow: triggers on push to feature branches (!main, !hotfix/*, etc.).
  • Destroy workflow: supports manual dispatch, branch deletion, and PR close cleanup.

Minimal example in .projenrc.ts

import { createCdkDeploymentWorkflows } from './src/bin/cicd-helper';

createCdkDeploymentWorkflows(project.github!, '111111111111', 'eu-west-1', 'test', 'GitHubActionsServiceRole', '22.18.0', true, ['test','production']);

git-helper.ts

Source: src/bin/git-helper.ts

getGitRepositoryDetails

Parses the Git remote URL from git config --get remote.origin.url to extract owner and repo. Used by the FoundationStack to scope the GitHub OIDC sub claim to repo:<owner>/<repo>:environment:<env>.

Usage

import { getGitRepositoryDetails } from '../bin/git-helper';
const { gitOwner, gitRepoName } = getGitRepositoryDetails();
← ConstructsStacks →