### Example BuildSpec.yaml Structure

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/developer_guides/ci.md

A sample buildspec.yaml file demonstrating the structure for defining installation, build, and post-build commands, including runtime versions for Node.js.

```yaml
version: 0.2

phases:
  install:
    runtime-versions:
      nodejs: 20
    commands:
      - npm ci
  build:
    commands:
      - npm run build
  post_build:
    commands:
      - npm run test
      - cdk synth
```

--------------------------------

### Complete package.json Example

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/workshops/github-pipeline/02-define-quality-gates-ci.md

This is an example of a complete package.json file after setting up quality gates and CI steps.

```json
--8<
    content/workshops/basics-lvl300/assets/code/package.json
--8<--
```

--------------------------------

### Start MCP Server

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/mcp/debugger.md

Make the start script executable and then run it to launch the MCP server. It checks for a virtual environment and activates it before starting.

```bash
chmod +x scripts/start.sh

./scripts/start.sh
```

--------------------------------

### Start Script

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/mcp-servers/debugger-mcp/README.md

The `start.sh` script starts the MCP server. It checks for the virtual environment, activates it, and then launches the MCP server.

```APIDOC
## scripts/start.sh

### Description
Starts the MCP server:
1. Checks if the virtual environment exists (prompts to run init.sh if not)
2. Activates the virtual environment
3. Launches the MCP server

### Usage
```bash
# Make the script executable (if not already)
chmod +x scripts/start.sh

# Start the MCP server
./scripts/start.sh
```
```

--------------------------------

### Example .npmrc Configuration

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/developer_guides/private_npm_registry.md

An example of a complete .npmrc file including a scoped registry URL and an authentication token.

```bash
# Content of .npmrc
@cdklabs:registry=https://jfrog.com/artifactory/api/npm/cdklabs-npm-release/
//jfrog.com/artifactory/api/npm/cdklabs-npm-release/:_authToken=eya......
```

--------------------------------

### Initialize Development Environment

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/mcp-servers/debugger-mcp/README.md

Runs the initialization script to set up the Python virtual environment, install uv, and install project dependencies.

```bash
# Make the initialization script executable (if not already)
chmod +x scripts/init.sh

# Run the initialization script
./scripts/init.sh
```

--------------------------------

### Initialization Script

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/mcp-servers/debugger-mcp/README.md

The `init.sh` script initializes the development environment by creating a Python virtual environment, installing the `uv` package manager, and installing all project dependencies.

```APIDOC
## scripts/init.sh

### Description
Initializes the development environment by:
1. Creating a Python virtual environment (if it doesn't exist)
2. Installing the `uv` package manager (if not already installed)
3. Installing all dependencies from pyproject.toml in development mode

### Usage
```bash
# Make the initialization script executable (if not already)
chmod +x scripts/init.sh

# Run the initialization script
./scripts/init.sh
```
```

--------------------------------

### Prepare Project with Taskfile

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/getting_started/projen_with_taskfile.md

Run this command to prepare your project after initial setup. It ensures all necessary configurations and dependencies are in place.

```bash
task prepare
```

--------------------------------

### Initialize Development Environment

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/mcp/debugger.md

Make the initialization script executable and then run it to set up the development environment, including creating a virtual environment and installing dependencies.

```bash
chmod +x scripts/init.sh

./scripts/init.sh
```

--------------------------------

### Pre-Build Phase Commands

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper/API.md

Optional array of phase commands to be executed before the build phase. This can include tasks like dependency installation or environment setup.

```typescript
public readonly preBuild: IPhaseCommand[];
```

--------------------------------

### Install ESLint for Code Styling

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/workshops/basics-lvl300/02-define-quality-gates-ci.md

Install ESLint and necessary plugins for code styling and static analysis in an NPM project.

```bash
npm install --save-dev eslint @eslint/core @eslint/js @types/eslint__js typescript typescript-eslint @stylistic/eslint-plugin
```

--------------------------------

### Initialize Sample Application for Development

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/contributing/index.md

Initializes a new project based on a selected sample application, setting the SAMPLE_APP environment variable and using Projen for setup. This creates a temporary 'development/project' folder.

```bash
export SAMPLE_APP=cdk-ts-example;
task samples:dev:init
```

--------------------------------

### Amazon Q CLI Usage Example

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/mcp/debugger.md

Example command for using the CDK CI/CD Wrapper Debugger with Amazon Q CLI to analyze a CDK project.

```bash
# Example usage (syntax may vary based on Amazon Q CLI version)
q chat "Use the cdk-cicd-wrapper-debugger to analyze my CDK project at ./my-project"
```

--------------------------------

### Initialize RepositoryConfig

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper/API.md

Example of initializing a RepositoryConfig object. This configuration specifies repository details.

```typescript
import { RepositoryConfig } from '@cdklabs/cdk-cicd-wrapper'

const repositoryConfig: RepositoryConfig = { ... }
```

--------------------------------

### Complete CDK CI/CD Example

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/workshops/basics-lvl300/04-develop-genai-solution.md

The complete bin/cdk-cicd-example.ts file after integrating the DEV stage and defining the Workbench.

```typescript
import 'source-map-support/register';
import * as cdk from 'aws-cdk-lib';
import * as path from 'path';
import * as wrapper from '@aws-cdk/pipelines-app-backend';
import { DemoStack } from '../lib/demo-stack';

const app = new cdk.App();

new wrapper.CDKPipelineAppBackend(app, {
  // Use 'aws-cdk-lib' for the core stack
  cdkAppPath: path.join(__dirname, 'cdk-cicd-example.ts'),
  // Define the stages for the pipeline
  defineStages([
    { stage: wrapper.Stage.RES, account: process.env.AWS_ACCOUNT_ID },
    { stage: wrapper.Stage.DEV, account: process.env.AWS_ACCOUNT_ID },
  ]),
  // Define the Workbench environment
  workbench({
    provide(context) {
      new DemoStack(context.scope, 'DemoStack', { env: context.environment });
    },
  }),
});

app.synth();

```

--------------------------------

### Install dependencies from Pipfile.lock

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/developer_guides/python_dependencies.md

Install all dependencies specified in the 'Pipfile.lock' file, ensuring exact versions are used for reproducible builds.

```bash
pipenv sync
```

--------------------------------

### Install CDK CI/CD Wrapper Packages

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/README.md

Install the necessary packages for the CDK CI/CD Wrapper and its CLI tool using npm.

```bash
npm i @cdklabs/cdk-cicd-wrapper @cdklabs/cdk-cicd-wrapper-cli
```

--------------------------------

### Complete package.json for Quality Gates

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/workshops/basics-lvl300/02-define-quality-gates-ci.md

This is an example of a complete package.json file incorporating all defined quality gates and CI steps.

```json
{
  "name": "cdk-workshop",
  "version": "0.1.0",
  "bin": {
    "cdk-workshop": "bin/cdk-workshop.js"
  },
  "scripts": {
    "build": "tsc",
    "watch": "tsc -w",
    "test": "jest",
    "lint": "eslint . --ext .ts",
    "cdk": "cdk",
    "audit": "concurrently \'npm:audit:*\'",
    "audit:license": "license-checker --summary --json > .license.json",
    "validate": "cdk synth --quiet"
  },
  "devDependencies": {
    "@aws-cdk/assert": "^2.0.0",
    "@aws-cdk/core": "^2.0.0",
    "@types/jest": "^26.0.10",
    "@types/node": "^14.14.6",
    "@typescript-eslint/eslint-plugin": "^4.6.0",
    "eslint": "^7.12.1",
    "eslint-plugin-import": "^2.22.1",
    "jest": "^26.4.2",
    "ts-node": "^9.0.0",
    "typescript": "~3.9.7",
    "concurrently": "^7.0.0",
    "license-checker": "^4.0.0"
  },
  "dependencies": {
    "@aws-cdk/core": "^2.0.0",
    "constructs": "^10.0.0"
  }
}
```

--------------------------------

### Example package.json Scripts Section

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/getting_started/index.md

Illustrates the 'scripts' section of a package.json file after modifications, showing various audit, linting, and testing commands.

```json
{
  ...
  "scripts": {
    "audit:deps:nodejs": "cdk-cicd check-dependencies --npm",
    "audit:deps:python": "cdk-cicd check-dependencies --python",
    "audit:fix:license": "npm run license:fix",
    "audit:license": "npm run license",
    "audit:scan:security": "cdk-cicd security-scan --bandit --semgrep --shellcheck --ci",
    "audit": "npx concurrently 'npm:audit:*(!fix)'",
    "cdk": "npx aws-cdk@2.162.1",
    "license:fix": "cdk-cicd license --fix",
    "license": "cdk-cicd license",
    "lint:fix": "eslint . --ext .ts --fix",
    "lint": "eslint . --ext .ts --max-warnings 0",
    "test": "jest",
    "validate:fix": "cdk-cicd validate --fix",
    "validate": "cdk-cicd validate",
    ...
  }
  ...
}
```

--------------------------------

### Install CDK CI/CD Wrapper CLI Globally

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper-cli/README.md

Installs the CDK CI/CD Wrapper CLI globally using npm. Requires Node.js and npm.

```bash
npm install -g @cdklabs/cdk-cicd-wrapper-cli
```

--------------------------------

### Correct Commit Message Example

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/contributing/index.md

This example demonstrates a correctly formatted commit message that adheres to conventional commit standards.

```bash
> git commit -m "docs: updated README.md with better instructions for the commit-msg hook"

> cdk-cicd-wrapper@1.2.3 commitlint
> commitlint --edit .git/COMMIT_EDITMSG

[feat/developer-tools 24192d7] docs: updated README.md with better instructions for the commit-msg hook
 1 file changed, 1 insertion(+), 1 deletion(-)
```

--------------------------------

### Example: Add Stages to a Wave

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper/API.md

Demonstrates how to create a Wave and add multiple application stages to it for parallel deployment.

```typescript
declare const pipeline: pipelines.CodePipeline;

const wave = pipeline.addWave('MyWave');
wave.addStage(new MyApplicationStage(this, 'Stage1'));
wave.addStage(new MyApplicationStage(this, 'Stage2'));
```

--------------------------------

### Example MCP Server Usage Prompt

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/mcp/index.md

Use this prompt with any MCP-compatible AI assistant to initiate a project analysis using the cdk-cicd-wrapper-debugger.

```plaintext
"Can you use the cdk-cicd-wrapper-debugger to check my project configuration?"
```

--------------------------------

### Full CDK CI/CD Example Configuration

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/workshops/basics-lvl300/06-develop-genai-solution-part-2.md

The complete 'bin/cdk-cicd-example.ts' file, showing the Workbench configuration with the feature flag enabled by default. This file is the entry point for the CDK application.

```typescript
#!/usr/bin/env node
import 'source-map-support/register';
import * as cdk from 'aws-cdk-lib';
import { DemoStack } from '../lib/demo-stack';

const app = new cdk.App();

new DemoStack(app, 'DemoStack', {
  env: {
    account: process.env.CDK_DEFAULT_ACCOUNT,
    region: process.env.CDK_DEFAULT_REGION,
  },
});

app.synth();

new cdk. pipelines.CodePipeline(app, 'Pipeline', {
  pipelineName: 'cdk-cicd-wrapper-pipeline',
  synth: new cdk.pipelines.ShellStep('Synth', {
    inputСм: cdk.pipelines.Artifact.artifact(
      'cdk.out'
    ),
    commands: [
      'npm ci',
      'npm run build',
      'npx cdk synth',
    ],
  }),
})
  .addStage(new PipelineStage(app, 'PipelineStage', {
    env: {
      account: process.env.CDK_DEFAULT_ACCOUNT,
      region: process.env.CDK_DEFAULT_REGION,
    },
  }))
  .workbench({
    provide(context) {
      context.scope.node.setContext('feature-streamlit', true);
      new DemoStack(context.scope, 'DemoStack', { env: context.environment });
    },
  });

```

--------------------------------

### Deploy Workbench Environment

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/workshops/basics-lvl300/06-develop-genai-solution-part-2.md

Command to deploy the Workbench environment. This command initiates the deployment process for the entire setup.

```bash
npm run workbench deploy -- --all
```

--------------------------------

### Initialize ProxyProps

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper/API.md

Example of initializing a ProxyProps object. This configuration is used for proxy settings.

```typescript
import { ProxyProps } from '@cdklabs/cdk-cicd-wrapper'

const proxyProps: ProxyProps = { ... }
```

--------------------------------

### Example package.json scripts section

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/README.md

A sample 'scripts' section for package.json demonstrating the integration of various CDK CI/CD Wrapper commands and common tools like ESLint and Jest.

```json
{
  "...": "...",
  "scripts": {
    "validate": "cdk-cicd validate",
    "validate:fix": "cdk-cicd validate --fix",
    "audit": "npx concurrently 'npm:audit:*(!fix)'",
    "audit:deps:nodejs": "cdk-cicd check-dependencies --npm",
    "audit:deps:python": "cdk-cicd check-dependencies --python",
    "audit:scan:security": "cdk-cicd security-scan --bandit --semgrep --shellcheck --ci",
    "audit:license": "npm run license",
    "audit:fix:license": "npm run license:fix",
    "license": "cdk-cicd license",
    "license:fix": "cdk-cicd license --fix",
    "lint": "eslint . --ext .ts --max-warnings 0",
    "lint:fix": "eslint . --ext .ts --fix",
    "test": "jest"
    "...": "..."
  }
  "..."
}
```

--------------------------------

### Initialize New Project with Projen

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/getting_started/projen_with_taskfile.md

Use this command to initialize a new AWS CDK TypeScript app project with a specified dependency. Ensure you have Node.js and npm installed.

```bash
npx projen@latest new awscdk-app-ts --no-git --deps {{ npm_projen }}
```

--------------------------------

### Minimal Pipeline Setup with PipelineBlueprint.builder()

Source: https://context7.com/cdklabs/cdk-cicd-wrapper/llms.txt

Configures and synthesizes a minimal pipeline infrastructure using the primary entry point. Reads account IDs from environment variables.

```typescript
import * as cdk from 'aws-cdk-lib';
import { PipelineBlueprint, Stage } from '@cdklabs/cdk-cicd-wrapper';

const app = new cdk.App();

// Minimal pipeline: reads ACCOUNT_RES, ACCOUNT_DEV, ACCOUNT_INT from env
PipelineBlueprint.builder()
  .defineStages([Stage.RES, Stage.DEV, Stage.INT])
  .synth(app);
```

--------------------------------

### Initialize PRCheckConfig

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper/API.md

Example of initializing a PRCheckConfig object. Ensure all required properties are provided.

```typescript
import { PRCheckConfig } from '@cdklabs/cdk-cicd-wrapper'

const pRCheckConfig: PRCheckConfig = { ... }
```

--------------------------------

### ResourceContext.initStage Method

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper/API.md

Initializes a stage within the resource context. This is typically called during pipeline setup.

```typescript
public initStage(stage: string): void
```

--------------------------------

### Basic Pipeline Setup with CDK CI/CD Wrapper

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/README.md

Initialize the PipelineBlueprint in your CDK application's entry file. This sets up the CI/CD pipeline with default configurations without deploying any stacks to staging accounts.

```typescript
import * as cdk from 'aws-cdk-lib';
import { PipelineBlueprint } from '@cdklabs/cdk-cicd-wrapper';

const app = new cdk.App();

PipelineBlueprint.builder().synth(app);
```

--------------------------------

### Configure Stacks with PipelineBlueprint

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/getting_started/projen_with_taskfile.md

Use the PipelineBlueprint to define and configure application stacks. This example shows how to add stacks and pass necessary context to them.

```typescript
import * as cdk from 'aws-cdk-lib';
import { PipelineBlueprint } from '{{ npm_codepipeline }}';

const app = new cdk.App();

PipelineBlueprint.builder().addStack({
  provide: (context) => {
    // Create your stacks here
    new YourStack(context.scope, `${context.blueprintProps.applicationName}YourStack`, {
      applicationName: context.blueprintProps.applicationName,
      stageName: context.stage,
    });
    new YourOtherStack(context.scope, `${context.blueprintProps.applicationName}YourOtherStack`, {
      applicationQualifier: context.blueprintProps.applicationQualifier,
      encryptionKey: context.get(GlobalResources.Encryption)!.kmsKey,
    });
  }
}).synth(app);
```

--------------------------------

### Configure Local Environment with CLI Tool

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/getting_started/index.md

Run the CLI configure command to simplify the setup of your CI/CD pipeline. Follow the on-screen instructions and be aware of the default stages (RES, DEV, INT, PROD) and GitHub ARN requirements.

```bash
npx {{ npm_cli }}@latest configure
```

--------------------------------

### Bootstrap CDK for Multi-Account Setup

Source: https://context7.com/cdklabs/cdk-cicd-wrapper/llms.txt

Bootstrap each AWS account with a cross-account trust relationship pointing to the RES account. Ensure CDK_QUALIFIER is set from package.json.

```bash
export CDK_QUALIFIER=$(jq -r '.config.cdkQualifier' package.json)

# RES account (no trust needed — this is where the pipeline lives)
npx dotenv-cli -- npm run cdk bootstrap -- \
  --profile $RES_ACCOUNT_AWS_PROFILE \
  --qualifier ${CDK_QUALIFIER} \
  aws://${ACCOUNT_RES}/${AWS_REGION}

# DEV account (trusts RES)
npx dotenv-cli -- npm run cdk bootstrap -- \
  --profile $DEV_ACCOUNT_AWS_PROFILE \
  --qualifier ${CDK_QUALIFIER} \
  --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess \
  --trust ${ACCOUNT_RES} \
  aws://${ACCOUNT_DEV}/${AWS_REGION}

# INT account (trusts RES)
npx dotenv-cli -- npm run cdk bootstrap -- \
  --profile $INT_ACCOUNT_AWS_PROFILE \
  --qualifier ${CDK_QUALIFIER} \
  --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess \
  --trust ${ACCOUNT_RES} \
  aws://${ACCOUNT_INT}/${AWS_REGION}

# Initial deployment (creates pipeline in RES account)
npx dotenv-cli -- npm run cdk deploy -- \
  --all --region ${AWS_REGION} \
  --profile $RES_ACCOUNT_AWS_PROFILE \
  --qualifier ${CDK_QUALIFIER}
```

--------------------------------

### Run CDK CI/CD Wrapper CLI with npx

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper-cli/README.md

Executes the CDK CI/CD Wrapper CLI without global installation using npx. Replace '[command]' with the desired CLI command.

```bash
npx @cdklabs/cdk-cicd-wrapper-cli [command]
```

--------------------------------

### SSMParameterStack Stack ID Example

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper/API.md

An example of the resolved stack ID, which is an ARN.

```typescript
// After resolving, looks like
'arn:aws:cloudformation:us-west-2:123456789012:stack/teststack/51af3dc0-da77-11e4-872e-1234567db123'
```

--------------------------------

### List Available Sample Applications

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/contributing/index.md

Lists all available sample applications within the repository.

```bash
task samples:list
```

--------------------------------

### Install cdk-cicd-wrapper Packages

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/contributing/index.md

Installs the cdk-cicd-wrapper packages from AWS CodeArtifact into a CDK project.

```bash
npm install --save @cdklabs/cdk-cicd-wrapper @cdklabs/cdk-cicd-wrapper-cli
```

--------------------------------

### CLI Commands for CDK-CICD Wrapper

Source: https://context7.com/cdklabs/cdk-cicd-wrapper/llms.txt

Utilize CLI commands for interactive environment setup, validating package-lock.json, managing license headers, and performing dependency and security vulnerability checks.

```bash
# Interactive environment setup — generates .env and updates package.json config
npx cdk-cicd configure

# Validate package-lock.json integrity (creates package-verification.json on first run)
npx cdk-cicd validate
npx cdk-cicd validate --fix   # regenerate verification file

# License header checks and NOTICE file generation
npx cdk-cicd license
npx cdk-cicd license --fix    # auto-add headers and regenerate NOTICE

# Dependency vulnerability scanning
npx cdk-cicd check-dependencies --npm     # npm audit via better-npm-audit
npx cdk-cicd check-dependencies --python  # pip-audit for Python dependencies

# Static security scanning (runs semgrep, bandit, shellcheck)
npx cdk-cicd security-scan --semgrep --bandit --shellcheck
npx cdk-cicd security-scan --semgrep --bandit --shellcheck --ci  # JUnit/Checkstyle output

# Typical package.json scripts block generated by the CLI:
# {
#   "validate": "cdk-cicd validate",
#   "validate:fix": "cdk-cicd validate --fix",

```

--------------------------------

### Install Concurrently Dependency

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/workshops/basics-lvl300/02-define-quality-gates-ci.md

Install the 'concurrently' package as a dev dependency to manage parallel script execution.

```bash
npm install --save-dev concurrently
```

--------------------------------

### Install NPM Dependencies

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper/README.md

Install the necessary Node Package Manager (NPM) dependencies for the CDK CI/CD Wrapper.

```bash
npm install
```

--------------------------------

### Build and Serve Documentation Locally

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/contributing/index.md

Use these commands to build the MkDocs documentation and serve it locally for preview. The documentation will be available at http://localhost:8000.

```bash
task docs
```

```bash
task docs:local
```

--------------------------------

### Incorrect Commit Message Example

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/contributing/index.md

This example shows a commit message that will fail the commitlint check due to incorrect formatting.

```bash
> git commit -m "foo: this will fail"

> cdk-cicd-wrapper@1.2.3 commitlint
> commitlint --edit 

⧗   input: foo: this will fail
✖   type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test] [type-enum]

✖   found 1 problems, 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

husky - commit-msg hook exited with code 1 (error)
```

--------------------------------

### Initialize Code Repository

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/contributing/index.md

Execute the 'task init' command to initialize the code repository after cloning it from GitHub.

```bash
task init
```

--------------------------------

### Install git-remote-s3 Python Package

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/developer_guides/vcs_s3.md

Install the necessary Python package to use S3 as a Git remote. This is a prerequisite for the integration.

```bash
pip install git-remote-s3
```

--------------------------------

### Bootstrap DEV Stage with Projen

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/getting_started/projen.md

Use this command to prepare the DEV stage for deployment. Ensure your stages are defined in the `.projenrc.ts` file.

```bash
npm run bootstrap DEV
```

--------------------------------

### Bootstrap INT Stage with Projen

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/getting_started/projen.md

Use this command to prepare the INT stage for deployment. Ensure your stages are defined in the `.projenrc.ts` file.

```bash
npm run bootstrap INT
```

--------------------------------

### Bootstrap PROD Stage with Projen

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/getting_started/projen.md

Use this command to prepare the PROD stage for deployment, if configured. Ensure your stages are defined in the `.projenrc.ts` file.

```bash
npm run bootstrap PROD
```

--------------------------------

### Install a new Python dependency

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/developer_guides/python_dependencies.md

Use this command to install a new package into your Pipenv-managed virtual environment. The dependency will be added to your Pipfile.

```bash
pipenv install <dependency>
```

--------------------------------

### Bootstrap RES Stage with Projen

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/getting_started/projen.md

Use this command to prepare the RES stage for deployment. Ensure your stages are defined in the `.projenrc.ts` file.

```bash
npm run bootstrap RES
```

--------------------------------

### Install git-remote-codecommit

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/developer_guides/vcs_codecommit.md

Install the necessary tool for interacting with AWS CodeCommit repositories using HTTPS. This command requires sudo privileges.

```bash
sudo pip3 install git-remote-codecommit
```

--------------------------------

### CDK Pipeline Install Commands Property

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper/API.md

An array of strings representing commands to be executed during the installation phase of the pipeline. This is a required string array property.

```typescript
public readonly installCommands: string[];
```

--------------------------------

### Initialize Environment Object

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper/API.md

Demonstrates how to initialize an Environment object. Ensure the 'account' and 'region' properties are provided as they are required.

```typescript
import { Environment } from '@cdklabs/cdk-cicd-wrapper'

const environment: Environment = { ... }
```

--------------------------------

### Trunk-Based Development Pipeline Setup

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/developer_guides/gitbranchingstrategies.md

Configure the PipelineBlueprint for trunk-based development by defining stages and adding stacks. This setup assumes direct commits to the main trunk.

```typescript
PipelineBlueprint.builder()
    .defineStages([
        Stage.RES,
        Stage.DEV,
        Stage.INT,]
    )
    .addStack({
        provide: (context) => {
            new MyStack(context.scope, `${context.blueprintProps.applicationName}Stack`, {
        });
        },
    })
    .synth(app);
```

--------------------------------

### Display Sample Application Configuration Info

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/contributing/index.md

Verifies and displays the detected configuration for the sample application. Recommended when managing multiple AWS accounts.

```bash
task samples:dev:info
```

--------------------------------

### Cleaned CDK App Structure

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/workshops/basics-lvl300/03-create-pipeline.md

The CDK app structure after removing the example stack.

```typescript
#!/usr/bin/env node
import 'source-map-support/register';
import * as cdk from 'aws-cdk-lib';

const app = new cdk.App();

/*
 * Application configuration section. */
// new CdkCicdExampleStack(app, 'CdkCicdExampleStack', {
//   /* If you don't specify 'env', this stack will be environment-agnostic. 
//    * Account/Region-dependent features and context lookups will not work. 
//    * See https://docs.aws.amazon.com/cdk/latest/guide/environments.html */
//   /* For more information, see https://docs.aws.amazon.com/cdk/latest/guide/home.html#stack-props */
// });

```

--------------------------------

### Bootstrap AWS Accounts for Sample Application

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/contributing/index.md

Executes the necessary bootstrapping process for AWS accounts before the first deployment of the sample application.

```bash
task samples:dev:bootstrap
```

--------------------------------

### ResourceContext

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper/API.md

Provides API to register resource providers and get access to the provided resources.

```APIDOC
## Class: ResourceContext

### Description
Provides API to register resource providers and get access to the provided resources.

### Initializers
```typescript
new ResourceContext(_scope: Construct, pipelineStack: Construct, blueprintProps: IVanillaPipelineBlueprintProps)
```

#### Parameters
* **_scope** (Construct, Required) - No description.
* **pipelineStack** (Construct, Required) - No description.
* **blueprintProps** (IVanillaPipelineBlueprintProps, Required) - No description.

### Methods
* **get**(name: string): any
* **has**(name: string): boolean
* **initStage**(stage: string): void
```

--------------------------------

### VPCProvider Initializer and Methods

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper/API.md

Documentation for the VPCProvider class, including its initializer and methods for providing VPC configurations.

```APIDOC
## `VPCProvider` Initializer

### Description
Initializes a new instance of the VPCProvider.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **vpc** (IVpcConfig) - Optional - Configuration for the VPC.

### Request Example
```typescript
import { VPCProvider } from '@cdklabs/cdk-cicd-wrapper';

const vpcProvider = new VPCProvider({
  // vpc configuration details
});
```

### Response
#### Success Response (200)
Returns a new VPCProvider instance.

#### Response Example
```typescript
VPCProvider
```
```

```APIDOC
## `provide` Method for VPCProvider

### Description
Provides the VPC configuration for the CI/CD process.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **context** (ResourceContext) - Required - The resource context.

### Request Example
```typescript
// Assuming vpcProvider is an instance of VPCProvider and context is defined
vpcProvider.provide(context);
```

### Response
#### Success Response (200)
Returns the VPC configuration.

#### Response Example
```typescript
any
```
```

--------------------------------

### SSMParameterStack Template File Property

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper/API.md

The name of the CloudFormation template file generated during synthesis. Example: `MyStack.template.json`.

```typescript
public readonly templateFile: string;
```

--------------------------------

### Get CodeStarConnectRepositoryStack Instance

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper/API.md

Looks up the first stack scope in which the construct is defined. Fails if there is no stack up the tree.

```typescript
import { CodeStarConnectRepositoryStack } from '@cdklabs/cdk-cicd-wrapper'

CodeStarConnectRepositoryStack.of(construct: IConstruct)
```

--------------------------------

### Initialize VPCProvider

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper/API.md

Instantiate the legacy VPC Provider. Optionally configure with an `IVpcConfig` object.

```typescript
import { VPCProvider } from '@cdklabs/cdk-cicd-wrapper'

new VPCProvider(vpc?: IVpcConfig)
```

--------------------------------

### Clean npm Cache

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/workshops/basics-lvl300/faq.md

Use this command to clear the npm cache if you encounter 'npm install' errors, such as 'notarget'.

```bash
npm cache clean --force
```

--------------------------------

### Update cdk-cicd-wrapper Libraries in Development

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/contributing/index.md

Updates the installed packages to the latest version of cdk-cicd-wrapper within the development environment.

```bash
task samples:dev:update
```

--------------------------------

### Initialize a CDK TypeScript Project

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/workshops/basics-lvl300/01-create-cdk-project.md

Use this command to create a new CDK project with TypeScript as the language. This sets up the basic project structure and configuration files.

```bash
npx -y aws-cdk init --language typescript
```

--------------------------------

### Project Structure

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/contributing/index.md

Overview of the project's directory structure.

```bash
├── docs                                  # Documentation 
├── packages                              # Packages
│   └── @cdklabs
│       ├── cdk-cicd-wrapper              # CDK CI/CD Wrapper Blueprint
│       └── cdk-cicd-wrapper-cli          # CLI tools to support the Blueprint
├── projenrc                              # Projen source
├── samples                               # Samples folder for demonstrating various aspects of the tool
├── .projenrc.ts                          # Projen file to manage project structure
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── CONFIGVARS.md
├── CONTRIBUTING.md
├── LICENSE
├── NOTICE
├── OSS_License_Summary.csv
├── README.md
├── Taskfile.yml                          # Contains helpful tasks that are useful during development
├── bandit.yaml
├── licensecheck.json
├── package-verification.json
├── package.json
├── tsconfig.dev.json
├── tsconfig.json
└── yarn.lock
```

--------------------------------

### Get Stack from Construct

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper/API.md

Finds the nearest Stack scope for a given construct. Fails if no stack is found. Import SSMParameterStack.

```typescript
import { SSMParameterStack } from '@cdklabs/cdk-cicd-wrapper'

SSMParameterStack.of(construct: IConstruct)
```

--------------------------------

### Bootstrap INT Stage

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/getting_started/index.md

Prepare the INT (Integration) stage by bootstrapping the AWS CDK. This command includes administrator access policies and specifies the RES account as a trusted entity.

```bash
CDK_QUALIFIER=$(jq -r '.config.cdkQualifier' package.json)
npx dotenv-cli -- npm run cdk bootstrap -- --profile $INT_ACCOUNT_AWS_PROFILE --qualifier ${CDK_QUALIFIER} --cloudformation-execution-policies \
   arn:aws:iam::aws:policy/AdministratorAccess \
   --trust ${ACCOUNT_RES} aws://${ACCOUNT_INT}/${AWS_REGION}
```

--------------------------------

### PreDeployBuildStep Initializer

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper/API.md

Initializes a new instance of the PreDeployBuildStep class.

```APIDOC
## PreDeployBuildStep Constructor

### Description
Initializes a new instance of the `PreDeployBuildStep` class.

### Method
```typescript
new PreDeployBuildStep(stage: string, props: CodeBuildStepProps)
```

### Parameters
#### Path Parameters
* **stage** (string) - Required - The stage name for the build step.
* **props** (CodeBuildStepProps) - Required - Properties for the CodeBuildStep.

### Request Example
```typescript
import { PreDeployBuildStep } from '@cdklabs/cdk-cicd-wrapper'

new PreDeployBuildStep('MyStage', { /* CodeBuildStepProps */ })
```
```

--------------------------------

### Get ResourceContext Instance

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper/API.md

Retrieves the singleton instance of ResourceContext. This is typically used to access shared resources and context within the pipeline.

```typescript
import { ResourceContext } from '@cdklabs/cdk-cicd-wrapper'

ResourceContext.instance()
```

--------------------------------

### addMetadata

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper/API.md

Adds an arbitrary key-value pair to the stack's metadata, which gets translated to the Metadata section of the generated CloudFormation template.

```APIDOC
## addMetadata

### Description
Adds an arbitary key-value pair, with information you want to record about the stack.

These get translated to the Metadata section of the generated template.

> [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/metadata-section-structure.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/metadata-section-structure.html)

### Method
```typescript
public addMetadata(key: string, value: any): void
```

### Parameters
#### Path Parameters
- **key** (string) - Required - The metadata key.
- **value** (any) - Required - The metadata value.
```

--------------------------------

### Bootstrap RES Stage

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/getting_started/index.md

Prepare the RES (Resource) stage by bootstrapping the AWS CDK. Ensure you have the correct AWS profile and qualifier configured.

```bash
CDK_QUALIFIER=$(jq -r '.config.cdkQualifier' package.json)
npx dotenv-cli -- npm run cdk bootstrap -- --profile $RES_ACCOUNT_AWS_PROFILE --qualifier ${CDK_QUALIFIER} aws://${ACCOUNT_RES}/${AWS_REGION}
```

--------------------------------

### Deploy Pipeline with Projen

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/getting_started/projen.md

Run this command from your project's root directory to deploy the CI/CD pipeline. You will be prompted to confirm the deployment.

```bash
npm run deploy
```

--------------------------------

### Add License Scripts to package.json

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/getting_started/index.md

Appends 'license' and 'license:fix' scripts to your package.json file using jq. Ensure jq is installed.

```bash
jq --arg key "license" --arg val "cdk-cicd license" '.scripts[$key] = $val' package.json | jq . > package.json.tmp; mv package.json.tmp package.json;
jq --arg key "license:fix" --arg val "cdk-cicd license --fix" '.scripts[$key] = $val' package.json | jq . > package.json.tmp; mv package.json.tmp package.json;
```

--------------------------------

### Create a New CDK Project

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/getting_started/index.md

Use this command to initialize a new AWS CDK project with TypeScript as the language.

```bash
mkdir my-project
cd my-project
npx aws-cdk@latest init app --language typescript
```

--------------------------------

### Get IAM Role Name

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper/API.md

Retrieves the name for a specific IAM role based on account, region, stage name, and application name.

```typescript
import { LogRetentionRoleStack } from '@cdklabs/cdk-cicd-wrapper'

LogRetentionRoleStack.getRoleName(account: string, region: string, stageName: Stage, applicationName: string)
```

--------------------------------

### Get IAM Role ARN

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper/API.md

Retrieves the ARN for a specific IAM role based on account, region, stage name, and application name.

```typescript
import { LogRetentionRoleStack } from '@cdklabs/cdk-cicd-wrapper'

LogRetentionRoleStack.getRoleArn(account: string, region: string, stageName: Stage, applicationName: string)
```

--------------------------------

### Initial CDK App File

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/workshops/github-pipeline/03-create-pipeline.md

This is the initial state of the bin/cdk-cicd-wrapper-github.ts file before modifications.

```typescript
#!/usr/bin/env node
import 'source-map-support/register';
import * as cdk from 'aws-cdk-lib';

const app = new cdk.App();

```

--------------------------------

### Initialize HttpProxyProvider

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/packages/@cdklabs/cdk-cicd-wrapper/API.md

Instantiate the HttpProxyProvider to configure HTTP proxy settings for the pipeline. Optionally, provide an IProxyConfig object during initialization.

```typescript
import { HttpProxyProvider } from '@cdklabs/cdk-cicd-wrapper'

new HttpProxyProvider(proxy?: IProxyConfig)
```

--------------------------------

### Configure Git LFS with S3

Source: https://github.com/cdklabs/cdk-cicd-wrapper/blob/main/docs/content/developer_guides/vcs_s3.md

Set up Git Large File Storage (LFS) for your S3-based repository. This involves installing git-lfs and tracking files.

```bash
git-lfs-s3 install
git lfs track "*.zip"  # Track large files
git add .gitattributes
```