Integrations

Connect CDK Insights to your GitHub repositories and get analysis results posted directly on pull requests. Each PR comment includes a summary of findings grouped by severity, with specific resource paths and remediation guidance. Your team can review infrastructure issues alongside code changes without switching tools.

# Set your GitHub token
export GITHUB_TOKEN=ghp_your_token_here

# Run analysis with GitHub issue creation
npx cdk-insights scan --output markdown --with-issue

# Issues are created with full findings and remediation steps

The official CDK Insights GitHub Action runs analysis on every pull request. Configure severity thresholds to block merges when critical issues are found, upload SARIF results to the GitHub Security tab, and persist reports as downloadable artifacts. It works with both free static analysis and paid AI-powered recommendations.

name: CDK Insights
on: [pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - uses: instance-labs/cdk-insights-action@v1
        with:
          fail-on: critical,high
          pr-comment: true
          sarif-upload: true

Embed CDK Insights directly into your CDK application as an Aspect. Analysis runs during cdk synth, catching issues before they ever reach CloudFormation. This is useful for teams that want to enforce standards at the code level rather than relying on external tooling. The Aspect can be scoped to specific stacks or applied globally.

import { CdkInsightsAspect } from 'cdk-insights';
import { Aspects } from 'aws-cdk-lib';

// Apply to your entire app
Aspects.of(app).add(new CdkInsightsAspect({
  failOnSeverity: 'high',
  services: ['s3', 'iam', 'rds'],
}));

// Or scope to a specific stack
Aspects.of(myStack).add(new CdkInsightsAspect());

The CDK Insights CLI is the fastest way to scan your CDK stacks locally. Run it with npx for zero-install usage, or add it as a dev dependency for consistent versioning across your team. It supports filtering by AWS service, rule severity, and specific rule IDs. Results can be output in multiple formats for integration with other tools.

# Zero-install scan
npx cdk-insights scan

# Scan a specific stack
npx cdk-insights scan --stack MyStack

# Filter by service
npx cdk-insights scan --services s3,iam,rds

# Output as JSON for scripting
npx cdk-insights scan --output json > results.json

CDK Insights supports multiple output formats to fit your workflow. JSON output is ideal for scripting and programmatic processing. Markdown works well for GitHub issues and documentation. HTML generates a standalone report you can share with stakeholders. SARIF integrates with GitHub Code Scanning and other security dashboards.

# Default terminal output with colours
npx cdk-insights scan

# JSON for scripting and automation
npx cdk-insights scan --output json

# Markdown for GitHub issues and docs
npx cdk-insights scan --output markdown

# HTML for shareable reports
npx cdk-insights scan --output html

# SARIF for GitHub Code Scanning
npx cdk-insights scan --output sarif