Skip to main content
Skip to main content

Running in CI/CD Pipelines

CDK Insights is a CLI tool that runs in any CI/CD environment. Simply execute the command and process the output.

💡 How CDK Insights Works in CI/CD

CDK Insights is a standard CLI tool - there are no integrations or plugins required.

✅ GitHub Actions
  • • Run: npx cdk-insights scan --output markdown --withIssue
  • • CDK Insights creates GitHub issues automatically
  • • Requires GITHUB_TOKEN and GitHub CLI
📦 GitLab/Jenkins/etc.
  • • Run: npx cdk-insights scan --output json
  • • Parse the JSON output in your pipeline
  • • Create issues/reports using your platform's tools

Why Run CDK Insights in CI/CD?

Integrating CDK Insights with your CI/CD pipeline provides:

  • Automated Security Scanning - Catch security issues before they reach production
  • Quality Gates - Prevent deployments with critical infrastructure issues
  • Compliance Enforcement - Ensure your infrastructure meets organizational standards
  • Early Feedback - Provide immediate feedback to developers on infrastructure changes

Integration Strategies

Pull Request Analysis

Analyze CDK changes in pull requests before merging

Benefits:

  • Early issue detection
  • Code review integration
  • Prevents bad deployments

Implementation: Run analysis on PR events

Deployment Gates

Block deployments when critical issues are found

Benefits:

  • Prevents security issues
  • Enforces quality standards
  • Automated compliance

Implementation: Fail pipeline on critical issues

Scheduled Analysis

Regular analysis of infrastructure for drift detection

Benefits:

  • Continuous monitoring
  • Drift detection
  • Compliance tracking

Implementation: Run on schedule or triggers

Multi-Environment

Different analysis rules for different environments

Benefits:

  • Environment-specific rules
  • Flexible policies
  • Risk management

Implementation: Environment-specific configurations

Platform Usage Guide

GitHub Actions

Run with automatic GitHub issue/gist creation

✨ Special: Only platform where CDK Insights can automatically create issues

✅ What You Get

  • Automatic issue creation via --withIssue flag
  • Create gists for large reports
  • Uses GITHUB_TOKEN environment variable
  • Requires GitHub CLI (gh) or token

⚠️ Limitations

  • Only works with GitHub repositories
  • Limited free minutes

Other Platforms (GitLab, Jenkins, etc.)

Run as standard CLI tool, handle output yourself

✨ Special: You handle the JSON output - cdk-insights just runs and exits

✅ What You Get

  • Run: npx cdk-insights scan --output json
  • Parse JSON output in your pipeline
  • Use exit codes for deployment gates
  • Save markdown/JSON as artifacts

⚠️ Limitations

  • No automatic issue creation
  • Must manually process JSON output
  • No native reporting features

GitHub Actions Example

Complete GitHub Actions workflow for CDK Insights analysis:

name: CDK Insights Analysis

on:
  pull_request:
    branches: [main]
    paths:
      - 'lib/**'
      - 'bin/**'
      - 'cdk.json'
  push:
    branches: [main]

jobs:
  analyze:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Install CDK
        run: npm install -g aws-cdk
        
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1
          
      - name: Run CDK Insights Analysis
        run: npx cdk-insights scan --all --format json --ci --fail-on-critical
        env:
          CDK_INSIGHTS_LICENSE_KEY: ${{ secrets.CDK_INSIGHTS_LICENSE_KEY }}
          
      - name: Comment PR with results
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const results = fs.readFileSync('analysis-results.json', 'utf8');
            const data = JSON.parse(results);
            
            const comment = `## 🔍 CDK Insights Analysis Results
            
            **Total Issues Found:** ${data.summary.totalIssues}
            - 🔴 Critical: ${data.summary.critical}
            - 🟠 High: ${data.summary.high}
            - 🟡 Medium: ${data.summary.medium}
            - 🟢 Low: ${data.summary.low}
            
            ${data.summary.critical > 0 ? '⚠️ **Critical issues found!** Please review and fix before merging.' : '✅ No critical issues found.'}
            `;
            
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: comment
            });

Other Platforms Example (GitLab CI)

For GitLab CI, Jenkins, CircleCI, etc., run cdk-insights and handle the JSON output yourself:

⚠️ Important: This example just runs the CLI tool. You'll need to add your own steps to:

  • • Parse the JSON output file
  • • Create issues in your platform (GitLab issues, Jira tickets, etc.)
  • • Post comments on merge requests
  • • Send notifications to your team

CDK Insights doesn't have built-in integrations for these platforms - it's just a CLI tool that outputs JSON.

stages:
  - analyze

variables:
  CDK_INSIGHTS_LICENSE_KEY: "$CDK_INSIGHTS_LICENSE_KEY"

cdk-analysis:
  stage: analyze
  image: node:18
  before_script:
    - npm ci
    - npm install -g aws-cdk
  script:
    - npx cdk-insights scan --all --format json --ci --fail-on-critical
  artifacts:
    reports:
      junit: analysis-results.json
    paths:
      - analysis-results.json
  only:
    - merge_requests
    - main

After this runs: The JSON file contains all findings. You'd need to write your own script to create GitLab issues, post MR comments, etc.

Best Practices

Environment-Specific Configuration

Use different CDK Insights configurations for different environments

  • Stricter rules for production environments
  • Different output formats for different use cases
  • Environment-specific service filters

License Key Management

Securely manage CDK Insights license keys in CI/CD

  • Store license keys as encrypted secrets
  • Use environment-specific license keys
  • Rotate keys regularly for security

Failure Handling

Implement appropriate failure handling strategies

  • Fail fast on critical security issues
  • Allow warnings for non-critical issues
  • Provide clear failure messages and next steps

Performance Optimization

Optimize CI/CD performance for large CDK applications

  • Cache CDK synthesis outputs
  • Use parallel analysis for multiple stacks
  • Limit analysis scope when possible

Security Considerations

License Key Security

Store CDK Insights license keys as encrypted secrets in your CI/CD platform. Never commit license keys to version control.

AWS Credentials

Use least-privilege IAM roles for CI/CD environments. Ensure credentials have only the minimum permissions required for CDK synthesis and analysis.

Output Security

Be cautious when sharing analysis results publicly. Some outputs may contain sensitive infrastructure information.

Ready to Integrate CDK Insights?

Start with a simple integration and gradually add more sophisticated analysis and reporting features.

Configuration GuideGitHub Integration