Create Install Scripts

Create Install Scripts

Generate installation scripts, GitLab CI configuration, and CodeBuild deployment setup for AWS CDK projects.

When to Apply

Reference this skill when:

• Setting up deployment pipelines for CDK projects
• Creating interactive install.sh scripts
• Configuring GitLab CI/CD for AWS deployments
• Setting up AWS CodeBuild for Docker image builds
• Automating CDK deployment workflows

How It Works

1. Analyze the CDK project structure 2. Generate install.sh for interactive local deployments 3. Generate .gitlab-ci.yml for GitLab CI/CD 4. Generate buildspec.yml for AWS CodeBuild 5. Configure deployment variables and secrets

Prerequisites

• AWS CDK project initialized
• GitLab repository (for CI/CD)
• AWS credentials configured
• Docker (if using CodeBuild for images)

Usage

# Run the setup script
./scripts/setup-cicd.sh

# Or trigger via agent
"Set up CI/CD for my CDK project"
"Create install scripts for deployment"

Generated Files

References

• Install Script Guide - Complete install.sh creation guide
• GitLab CI Setup - GitLab CI/CD configuration
• CodeBuild Setup - AWS CodeBuild setup
• Common Pitfalls - Troubleshooting guide

Create Install Scripts Skill

Automate the generation of deployment infrastructure for AWS CDK projects. This skill creates CI/CD configurations and installation scripts for GitLab CI and AWS CodeBuild environments.

Quick Start

Installation

npx skills add https://github.com/aws-samples/sample-agent-skills-for-builders --skill create-install-scripts

First Use

# From your CDK project directory
./scripts/setup-cicd.sh

This will generate:

• install.sh - Interactive deployment script
• .gitlab-ci.yml - GitLab CI/CD pipeline configuration
• buildspec.yml - AWS CodeBuild specification

Usage Examples

Generate Installation Script

# Create an interactive install.sh for your CDK project
./scripts/setup-cicd.sh

With Agent

Ask your AI agent directly:

"Set up CI/CD for my CDK project"
"Create install scripts for deployment"
"Generate GitLab CI configuration"

File Structure

create-install-scripts/
├── SKILL.md                    # Skill definition and metadata
├── README.md                   # This file
├── scripts/
│   └── setup-cicd.sh          # Main setup automation script
└── references/
    ├── install-script-guide.md    # Detailed install.sh creation
    ├── gitlab-ci-setup.md         # GitLab CI/CD configuration
    ├── codebuild-setup.md         # AWS CodeBuild setup
    └── common-pitfalls.md         # Troubleshooting guide

Prerequisites

Before using this skill, ensure you have:

• AWS CDK Project - An initialized CDK project (run cdk init if needed)
• AWS Credentials - Configured in ~/.aws/credentials or environment variables
• GitLab Repository - For CI/CD integration (if using GitLab)
• Docker (optional) - Required only if using AWS CodeBuild for Docker image builds
• Node.js/npm - For CDK operations

Generated Files Overview

Documentation

For detailed information, refer to:

• [Install Script Guide](./references/install-script-guide.md) - Learn how to customize install.sh, handle environment variables, and add pre/post-deployment hooks
• [GitLab CI Setup](./references/gitlab-ci-setup.md) - Configure GitLab CI/CD pipelines, secrets, and deployment stages
• [CodeBuild Setup](./references/codebuild-setup.md) - Set up AWS CodeBuild for automated container builds and CDK deployments
• [Common Pitfalls](./references/common-pitfalls.md) - Troubleshoot common issues and best practices

Support & Contribution

For issues or questions, check the Common Pitfalls guide first. Contributions are welcome via pull requests.

Setup CodeBuild

Configure AWS CodeBuild for CDK deployment.

setup-cicd.sh Script

Copy scripts/setup-cicd.sh to your project and modify PROJECT_NAME:

#!/bin/bash
set -e

# Configuration - modify these as needed
REGION="${AWS_DEFAULT_REGION:-us-east-1}"
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
BUCKET_NAME="PROJECT-cicd-${ACCOUNT_ID}-${REGION}"  # Change PROJECT
PROJECT_NAME="PROJECT-deploy"                        # Change PROJECT
ROLE_NAME="PROJECT-codebuild-role"                   # Change PROJECT

buildspec.yml Template

version: 0.2

phases:
  install:
    runtime-versions:
      nodejs: 20
      python: 3.12
    commands:
      - echo "Installing pnpm..."
      - npm install -g pnpm
      - corepack enable

  pre_build:
    commands:
      - echo "Installing dependencies..."
      - pnpm install --frozen-lockfile
      - echo "Installing Python dependencies..."
      - cd packages/service && pip install -e . && cd ../..

  build:
    commands:
      - echo "Ensuring CDK is bootstrapped..."
      - |
        pnpm -C packages/cdk exec cdk bootstrap \
          -c stackName=${STACK_NAME:-PROJECT} \
          -c authMethod=${AUTH_METHOD:-cognito} \
          -c adminEmail=${ADMIN_EMAIL:-} \
          -c customDomain=${CUSTOM_DOMAIN:-} \
          -c acmCertificateArn=${ACM_CERTIFICATE_ARN:-} \
          -c oidcProvider=${OIDC_PROVIDER:-} \
          -c oidcClientId=${OIDC_CLIENT_ID:-}
      - echo "Deploying stack..."
      - |
        pnpm -C packages/cdk exec cdk deploy ${STACK_NAME:-PROJECT} \
          --require-approval never \
          -c stackName=${STACK_NAME:-PROJECT} \
          -c authMethod=${AUTH_METHOD:-cognito} \
          -c adminEmail=${ADMIN_EMAIL:-} \
          -c customDomain=${CUSTOM_DOMAIN:-} \
          -c acmCertificateArn=${ACM_CERTIFICATE_ARN:-} \
          -c oidcProvider=${OIDC_PROVIDER:-} \
          -c oidcClientId=${OIDC_CLIENT_ID:-}

  post_build:
    commands:
      - echo "Deployment completed at $(date)"
      - |
        if [ $CODEBUILD_BUILD_SUCCEEDING -eq 1 ]; then
          echo "SUCCESS: Deployed successfully"
        else
          echo "FAILED: Deployment failed"
        fi

cache:
  paths:
    - node_modules/**/*
    - packages/*/node_modules/**/*
    - /root/.cache/pip/**/*

CodeBuild Project Configuration

The setup-cicd.sh script creates:

1. S3 Bucket

• Name: {project}-cicd-{account}-{region}
• Versioning enabled
• Used for source code uploads

2. IAM Role

• Name: {project}-codebuild-role
• Trust policy for CodeBuild service
• WARNING: Uses AdministratorAccess - restrict for production

3. CodeBuild Project

• Name: {project}-deploy
• Source: S3 bucket
• Environment: aws/codebuild/standard:7.0 with privileged mode
• Timeout: 60 minutes
• CloudWatch Logs enabled

Machine-Parseable Output

The script outputs values for programmatic use:

echo "OUTPUT:BUCKET_NAME=${BUCKET_NAME}"
echo "OUTPUT:PROJECT_NAME=${PROJECT_NAME}"
echo "OUTPUT:REGION=${REGION}"
echo "OUTPUT:ROLE_ARN=${ROLE_ARN}"

Parse in install.sh:

setup_output=$(bash scripts/cicd/setup-cicd.sh 2>&1)
CICD_BUCKET=$(echo "$setup_output" | grep "^OUTPUT:BUCKET_NAME=" | cut -d'=' -f2)
CODEBUILD_PROJECT=$(echo "$setup_output" | grep "^OUTPUT:PROJECT_NAME=" | cut -d'=' -f2)

Triggering CodeBuild from install.sh

BUILD_INFO=$(aws codebuild start-build \
    --project-name "${CODEBUILD_PROJECT}" \
    --environment-variables-override \
        "name=STACK_NAME,value=${stackName}" \
        "name=AUTH_METHOD,value=${authMethod}" \
        "name=ADMIN_EMAIL,value=${adminEmail}" \
        ...)

BUILD_ID=$(echo "$BUILD_INFO" | jq -r '.build.id')

Log Streaming

Wait for log stream to be created, then stream:

LOG_GROUP="/aws/codebuild/${CODEBUILD_PROJECT}"
LOG_STREAM=$(echo "$BUILD_ID" | cut -d':' -f2)

# Wait for log stream
for i in $(seq 1 30); do
    STREAM_EXISTS=$(aws logs describe-log-streams \
        --log-group-name "$LOG_GROUP" \
        --log-stream-name-prefix "$LOG_STREAM" \
        --query 'logStreams[0].logStreamName' \
        --output text 2>/dev/null || echo "None")

    if [ "$STREAM_EXISTS" != "None" ] && [ -n "$STREAM_EXISTS" ]; then
        break
    fi
    sleep 10
done

# Stream logs (AWS CLI v2 required)
aws logs tail "$LOG_GROUP" \
    --log-stream-names "$LOG_STREAM" \
    --follow \
    --format short

Common Pitfalls

Common issues and solutions when creating CDK install scripts.

1. CDK Bootstrap Requires Context Parameters

If CDK app validates context parameters during initialization, cdk bootstrap also needs them.

Symptom:

Error: adminEmail is required when using Cognito authentication

Wrong:

pnpm -C packages/cdk exec cdk bootstrap

Correct:

pnpm -C packages/cdk exec cdk bootstrap \
  -c stackName=${STACK_NAME} \
  -c authMethod=${AUTH_METHOD} \
  -c adminEmail=${ADMIN_EMAIL} \
  ...

Note: cdk bootstrap is idempotent - safe to run every time before deploy.

2. Running CDK in Monorepos

Cannot use npx cdk directly in monorepos.

Wrong:

npx cdk deploy
cd packages/cdk && npx cdk deploy

Correct:

pnpm -C packages/cdk exec cdk deploy
# Or use script defined in root package.json
pnpm cdk:deploy

3. AWS CLI v1 vs v2

aws logs tail --follow is AWS CLI v2 only.

Symptom:

aws: error: argument operation: Invalid choice

Solution:

# Remove v1 if installed via pip
pip uninstall awscli

# Install v2
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "/tmp/awscliv2.zip"
unzip /tmp/awscliv2.zip -d /tmp
sudo /tmp/aws/install --update

# Verify
aws --version  # Should show aws-cli/2.x.x

4. ZIP Exclusion Patterns for Monorepos

Root-level patterns don't match subdirectories.

Wrong - only matches root level:

zip -r source.zip . \
  -x ".venv/*" \
  -x "cdk.out/*" \
  -x ".next/*"

Correct - matches all levels:

zip -r source.zip . \
  -x ".venv/*" \
  -x "*/.venv/*" \
  -x "cdk.out/*" \
  -x "*/cdk.out/*" \
  -x ".next/*" \
  -x "*/.next/*" \
  -x "node_modules/*" \
  -x "*/node_modules/*" \
  -x "sessions/*" \
  -x "test-data/*" \
  -x "*.zip"

5. Multi-line Scripts with eval

Cannot use eval $(cat script.sh) for multi-line scripts.

Wrong:

eval $(cat $deploy_script)

Correct:

bash "$deploy_script"

6. CodeBuild Log Stream Timing

Log stream isn't immediately available when build starts.

Solution - wait with retry:

for i in $(seq 1 30); do
    STREAM_EXISTS=$(aws logs describe-log-streams \
        --log-group-name "$LOG_GROUP" \
        --log-stream-name-prefix "$LOG_STREAM" \
        --query 'logStreams[0].logStreamName' \
        --output text 2>/dev/null || echo "None")

    if [ "$STREAM_EXISTS" != "None" ] && [ -n "$STREAM_EXISTS" ]; then
        echo "Log stream ready!"
        break
    fi
    echo "Waiting for logs... ($i/30)"
    sleep 10
done

7. Parsing JSON with grep vs jq

Using grep for JSON parsing is fragile.

Fragile:

BUILD_ID=$(echo "$BUILD_INFO" | grep -o '"id": "[^"]*"' | head -1 | cut -d'"' -f4)

Robust:

BUILD_ID=$(echo "$BUILD_INFO" | jq -r '.build.id')

8. Self-Signed Certificate Dependencies

Generating self-signed certificates requires openssl.

Check dependency:

if ! command -v openssl &> /dev/null; then
    echo "Error: openssl is required for certificate generation"
    exit 1
fi

9. setup-cicd.sh Output Parsing

Need machine-readable output format for scripting.

In setup-cicd.sh:

# Human-readable output first
echo "Setup Complete!"
echo "  Bucket: ${BUCKET_NAME}"

# Machine-readable output at end (with prefix)
echo "OUTPUT:BUCKET_NAME=${BUCKET_NAME}"
echo "OUTPUT:PROJECT_NAME=${PROJECT_NAME}"

In install.sh:

setup_output=$(bash scripts/cicd/setup-cicd.sh 2>&1)

# Hide machine-readable lines from user
echo "$setup_output" | grep -v "^OUTPUT:"

# Parse values
CICD_BUCKET=$(echo "$setup_output" | grep "^OUTPUT:BUCKET_NAME=" | cut -d'=' -f2)

10. Sensitive Files in Git

Deployment configs contain account IDs, ARNs, and emails.

Required .gitignore entries:

# Deployment configs
default_deploy*.sh
default_codebuild_deploy.sh

# Certificate files
*.key
*.crt
*.csr

11. CDK Bootstrap Not Found Error

Symptom:

SSM parameter /cdk-bootstrap/hnb659fds/version not found

Cause: CDK hasn't been bootstrapped in the target account/region.

Solution: Always run bootstrap before deploy (it's idempotent):

pnpm -C packages/cdk exec cdk bootstrap -c ...
pnpm -C packages/cdk exec cdk deploy -c ...

12. Wrong Parameter Passing Method

CDK supports two ways to pass parameters - using the wrong one will fail silently or with confusing errors.

Context Parameters (-c)

For apps using node.tryGetContext():

// CDK code
const stackName = this.node.tryGetContext('stackName');

# Command line
cdk deploy -c stackName=MyStack -c adminEmail=admin@example.com

CloudFormation Parameters (--parameters)

For stacks using CfnParameter:

// CDK code
new CfnParameter(this, 'VpcId', { type: 'String' });

# Command line
cdk deploy --parameters vpcId="vpc-12345"

Always inspect the CDK code first to determine which method is used:

• Search for tryGetContext → use -c
• Search for CfnParameter → use --parameters

Setup GitLab CI

Configure GitLab CI/CD pipeline for CDK deployment via CodeBuild.

.gitlab-ci.yml Template

default:
  image: public.ecr.aws/sam/build-python3.12:latest-x86_64
  tags:
    - arch:amd64
    - size:large

variables:
  GIT_SUBMODULE_STRATEGY: recursive
  GIT_SUBMODULE_DEPTH: 1
  GIT_SUBMODULE_FORCE_HTTPS: true

stages:
  - deploy

deploy:
  stage: deploy
  environment: $CI_COMMIT_BRANCH
  variables:
    AWS_CREDS_TARGET_ROLE: $AWS_CREDS_TARGET_ROLE
    AWS_DEFAULT_REGION: $AWS_DEFAULT_REGION
    AWS_CONFIG_FILE: $CI_BUILDS_DIR/.awscredentialvendor/config
    AWS_SHARED_CREDENTIALS_FILE: $CI_BUILDS_DIR/.awscredentialvendor/credentials
  script:
    # Install dependencies
    - |
      if command -v dnf &>/dev/null; then
        dnf install -y zip jq -q
      elif command -v yum &>/dev/null; then
        yum install -y zip jq -q
      elif command -v apt-get &>/dev/null; then
        apt-get update && apt-get install -y zip jq
      fi

    # 1. Package source code
    - echo "Packaging source code..."
    - |
      zip -r source.zip . \
        -x ".git/*" \
        -x "node_modules/*" \
        -x "*/node_modules/*" \
        -x "cdk.out/*" \
        -x "*/cdk.out/*" \
        -x "*.pyc" \
        -x "*/__pycache__/*" \
        -x ".venv/*" \
        -x "*/.venv/*" \
        -x ".next/*" \
        -x "*/.next/*" \
        -x "sessions/*" \
        -x "test-data/*" \
        -x "*.zip"
    - echo "Package size:" && ls -lh source.zip

    # 2. Upload to S3
    - echo "Uploading to S3..."
    - aws s3 cp source.zip s3://${CICD_BUCKET}/source/source.zip

    # 3. Trigger CodeBuild
    - |
      echo "Starting CodeBuild..."
      BUILD_INFO=$(aws codebuild start-build \
        --project-name ${CODEBUILD_PROJECT} \
        --environment-variables-override \
          name=DEPLOY_ENV,value=${CI_COMMIT_BRANCH} \
          name=AUTH_METHOD,value=${AUTH_METHOD:-cognito} \
          name=ADMIN_EMAIL,value=${ADMIN_EMAIL:-} \
          name=CUSTOM_DOMAIN,value=${CUSTOM_DOMAIN:-} \
          name=ACM_CERTIFICATE_ARN,value=${ACM_CERTIFICATE_ARN:-} \
          name=OIDC_PROVIDER,value=${OIDC_PROVIDER:-} \
          name=OIDC_CLIENT_ID,value=${OIDC_CLIENT_ID:-})

      BUILD_ID=$(echo $BUILD_INFO | jq -r '.build.id')
      echo "CodeBuild started: $BUILD_ID"

    # 4. Wait for log stream
    - |
      LOG_GROUP="/aws/codebuild/${CODEBUILD_PROJECT}"
      LOG_STREAM=$(echo $BUILD_ID | cut -d':' -f2)

      for i in $(seq 1 30); do
        STREAM_EXISTS=$(aws logs describe-log-streams \
          --log-group-name "$LOG_GROUP" \
          --log-stream-name-prefix "$LOG_STREAM" \
          --query 'logStreams[0].logStreamName' \
          --output text 2>/dev/null || echo "None")

        if [ "$STREAM_EXISTS" != "None" ] && [ -n "$STREAM_EXISTS" ]; then
          echo "Log stream ready!"
          break
        fi
        echo "Waiting for logs... ($i/30)"
        sleep 10
      done

    # 5. Stream logs
    - |
      # Monitor build status in background
      (
        while true; do
          STATUS=$(aws codebuild batch-get-builds --ids $BUILD_ID \
            --query 'builds[0].buildStatus' --output text 2>/dev/null)
          if [ "$STATUS" != "IN_PROGRESS" ]; then
            echo "$STATUS" > /tmp/build_status
            break
          fi
          sleep 10
        done
      ) &
      MONITOR_PID=$!

      # Stream logs (AWS CLI v2)
      aws logs tail "$LOG_GROUP" \
        --log-stream-names "$LOG_STREAM" \
        --follow \
        --format short &
      LOGS_PID=$!

      # Wait for build completion
      while [ ! -f /tmp/build_status ]; do
        sleep 5
      done

      sleep 5
      kill $LOGS_PID 2>/dev/null || true
      kill $MONITOR_PID 2>/dev/null || true

      FINAL_STATUS=$(cat /tmp/build_status)
      if [ "$FINAL_STATUS" = "SUCCEEDED" ]; then
        exit 0
      else
        exit 1
      fi
  only:
    - develop
    - stage
    - main

Required GitLab CI/CD Variables

Notes

• The SAM build image includes AWS CLI v2 and Python
• zip and jq need to be installed at runtime
• Log streaming requires AWS CLI v2 (aws logs tail --follow)

Create Install Script

Create an interactive installation script for CDK projects supporting both local and CodeBuild deployment.

Script Structure

#!/bin/bash

# 1. Deployment method selection
echo "Deployment Method"
echo "  1. Local deployment (requires Node.js, pnpm, Docker)"
echo "  2. AWS CodeBuild deployment (no local tools required)"

# 2. Check for previous configuration
if [ -f "$deploy_script" ]; then
    # Ask to reuse
fi

# 3. Interactive configuration collection
#    - Stack name
#    - Auth method (Cognito/OIDC)
#    - Domain and certificate
#    - Storage configuration

# 4. Execute deployment
if [ "$useCodeBuild" == "true" ]; then
    # CodeBuild deployment
else
    # Local deployment
fi

Key Configuration Options

Authentication Methods

# Cognito mode
authMethod="cognito"
adminEmail="admin@example.com"
additionalIdp=""  # Optional external IdP

# OIDC mode
authMethod="oidc"
oidcProvider="https://cognito-idp.region.amazonaws.com/pool_id"
oidcClientId="client_id"

Self-Signed Certificate Generation

if [ -z "$customDomain" ]; then
    cert_dir=$(mktemp -d)
    cert_domain="project-selfsigned.local"

    # Generate private key
    openssl genrsa -out "$cert_dir/private.key" 2048 2>/dev/null

    # Generate CSR
    openssl req -new -key "$cert_dir/private.key" -out "$cert_dir/cert.csr" \
        -subj "/C=US/ST=State/L=City/O=Organization/OU=Unit/CN=$cert_domain" 2>/dev/null

    # Generate self-signed certificate
    openssl x509 -req -days 365 -in "$cert_dir/cert.csr" \
        -signkey "$cert_dir/private.key" -out "$cert_dir/certificate.crt" 2>/dev/null

    # Upload to ACM
    acmCertificateArn=$(aws acm import-certificate \
        --certificate fileb://"$cert_dir/certificate.crt" \
        --private-key fileb://"$cert_dir/private.key" \
        --query 'CertificateArn' \
        --output text)

    rm -rf "$cert_dir"
fi

Storage Configuration

# Serverless options (recommended)
useNeptuneServerless="true"
useOpenSearchServerless="true"
useRdsServerless="true"

Local Deployment Script Format

Generated default_deploy.sh should be a standalone executable script:

#!/bin/bash
# Bootstrap CDK (idempotent)
pnpm -C packages/cdk exec cdk bootstrap \
  -c stackName=PROJECT \
  -c authMethod=cognito \
  -c adminEmail=admin@example.com \
  ...

# Deploy
pnpm cdk:deploy PROJECT \
  -c stackName=PROJECT \
  -c authMethod=cognito \
  -c adminEmail=admin@example.com \
  ... \
  --require-approval never

.gitignore Configuration

# Deployment configs (contain sensitive info)
default_deploy*.sh
default_codebuild_deploy.sh

# Certificate files
*.key
*.crt
*.csr

Dependency Checks

Check for required dependencies at script start:

# Check AWS CLI version
aws_version=$(aws --version 2>&1)
if [[ "$aws_version" == *"aws-cli/1"* ]]; then
    echo "Warning: AWS CLI v1 detected. v2 is recommended for log streaming."
fi

# Check openssl (required for self-signed certs)
if ! command -v openssl &> /dev/null; then
    echo "Error: openssl is required for certificate generation"
    exit 1
fi