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 automatically detects CI environments and adjusts its behavior accordingly. When in CI mode, it disables interactive prompts, defaults to analyzing all stacks with JSON output, and skips caching for fresh analysis.

✅ GitHub Actions (Recommended)
  • • Use: TheLeePriest/cdk-insights-action@v1
  • • Automatic PR comment summaries
  • • SARIF upload to GitHub Code Scanning
  • • Or use CLI with --prComment flag
📦 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

✅ Automatic CI Detection

CDK Insights automatically detects these CI platforms:

• GitHub Actions• GitLab CI• CircleCI• Travis CI• Jenkins• AWS CodeBuild• Azure Pipelines• Bitbucket Pipelines• TeamCity• Buildkite• Drone• Semaphore

For other CI systems, set CI=true to enable CI mode.

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

Full-featured integration with PR comments and SARIF uploads

✨ Special: Use the official GitHub Action for the easiest setup

✅ What You Get

  • Official GitHub Action available
  • Automatic PR comment summaries via --prComment flag
  • SARIF upload to GitHub Code Scanning
  • Automatic issue creation via --with-issue flag
  • CI environment auto-detected

⚠️ 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'

jobs:
  analyze:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      security-events: write

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      # Option 1: Use the official GitHub Action (recommended)
      - name: CDK Insights Analysis
        uses: TheLeePriest/cdk-insights-action@v1
        with:
          license-key: ${{ secrets.CDK_INSIGHTS_LICENSE_KEY }}
          ai-analysis: true
          fail-on: critical,high
          pr-comment: true
          sarif-upload: true
          upload-artifact: true

      # Option 2: Use CLI directly with --prComment flag
      # - name: Run CDK Insights Analysis
      #   run: npx cdk-insights scan --all --prComment --failOnCritical
      #   env:
      #     CDK_INSIGHTS_LICENSE_KEY: ${{ secrets.CDK_INSIGHTS_LICENSE_KEY }}

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:20
  before_script:
    - npm ci
    - npm install -g aws-cdk
  script:
    - npx cdk-insights scan --all --output json --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 the official GitHub Action for the easiest setup, or use the CLI directly in any CI/CD platform.

GitHub Action SetupConfiguration Guide

Documentation

CI/CD Integration

Docs Home