GitHub Action

The official CDK Insights GitHub Action provides seamless integration with your CI/CD pipeline, including PR comments, SARIF uploads, and configurable quality gates.

TheLeePriest/cdk-insights-action

Available on GitHub Marketplace

View on GitHub

Features

PR Comments

Automatic analysis summaries posted directly on pull requests

Code Scanning

Auto-upload SARIF to GitHub Security tab for vulnerability tracking

Report Artifacts

JSON, SARIF, and markdown reports persisted as downloadable artifacts

Quality Gates

Block merges when critical or high severity issues are found

Quick Start

Add this workflow to your repository at .github/workflows/cdk-insights.yml:

name: CDK Insights
on: [pull_request]

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

    steps:
      - uses: actions/checkout@v4

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

      - name: Install dependencies
        run: npm ci

      - name: CDK Insights Analysis
        uses: TheLeePriest/cdk-insights-action@v1
        with:
          license-key: ${{ secrets.CDK_INSIGHTS_LICENSE_KEY }}
          ai-analysis: true

PR Comment Preview

When pr-comment: true (default), the action posts a formatted summary directly on your pull request:

## 🔍 CDK Insights Analysis

**Stack:** MyStack | **Resources:** 47 | **Issues:** 19 | **Analysis:** AI-powered

### Summary by Severity

| Severity | Count |
|----------|-------|
| 🔴 Critical | 2 |
| 🟠 High | 5 |
| 🟡 Medium | 12 |

### Top Issues

1. **S3 bucket without encryption** 🔴
   `MyStack/DataBucket` - Enable server-side encryption

2. **Lambda without DLQ** 🟠
   `MyStack/ProcessorFunction` - Add dead-letter queue

<details>
<summary>View all 19 issues</summary>
...
</details>

Note: The action updates existing CDK Insights comments instead of creating duplicates, keeping your PR clean on subsequent pushes.

Inputs

Input	Description	Default
license-key	CDK Insights license key (required for AI analysis)	`-`
working-directory	Directory containing CDK project	`.`
stack-name	Specific stack to analyze	`(all stacks)`
ai-analysis	Enable AI-powered recommendations	`false`
fail-on	Fail on severity levels (critical,high,medium,low)	`-`
pr-comment	Post analysis summary as PR comment	`true`
sarif-upload	Generate SARIF and auto-upload to GitHub Code Scanning	`false`
upload-artifact	Upload report files (JSON, SARIF, markdown) as a GitHub artifact	`true`
artifact-name	Name for the uploaded artifact	`cdk-insights-report`
github-token	GitHub token for SARIF upload to Code Scanning	`github.token`
services	Filter to specific AWS services (comma-separated)	`(all)`
rule-filter	Filter to specific rules (comma-separated)	`-`

Outputs

Output	Description
total-issues	Total number of issues found
critical-count	Number of critical issues
high-count	Number of high severity issues
medium-count	Number of medium severity issues
low-count	Number of low severity issues
sarif-file	Path to SARIF file (if generated)
json-file	Path to JSON results file
artifact-id	ID of the uploaded artifact (if upload-artifact is enabled)
exit-code	Exit code (0 = no issues at fail-on severity, 1 = issues found)

Complete Example

A full workflow with SARIF upload, failure thresholds, and output usage:

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  # Required for SARIF upload

    steps:
      - 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

      - name: CDK Insights Analysis
        id: 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       # Auto-uploads to Security tab
          upload-artifact: true    # Persists reports as artifacts

Required Permissions

The action requires different permissions depending on which features you enable:

permissions:
  contents: read        # Always required
  pull-requests: write  # Required for PR comments
  security-events: write  # Required for SARIF upload

contents: read

Always required to checkout code

pull-requests: write

Required for PR comments

security-events: write

Required for SARIF upload

Artifacts & Code Scanning

Report Artifacts

By default, all report files (JSON, SARIF, and markdown) are uploaded as a downloadable GitHub artifact. Find them in the workflow run summary under "Artifacts". This makes it easy to feed results into other tools or archive them for compliance.

# Customize artifact name (useful for monorepos)
- uses: TheLeePriest/cdk-insights-action@v1
  with:
    artifact-name: security-report-${{ matrix.project }}

SARIF & Code Scanning

When sarif-upload: true, the action generates SARIF files and automatically uploads them to GitHub's Security tab. No extra workflow steps needed — findings appear alongside other code scanning results.

Note: SARIF upload requires security-events: write permission. For private repos, GitHub Advanced Security must be enabled. Public repos work out of the box.

CLI Alternative

You can also use the CLI directly with the --prComment flag:

npx cdk-insights scan --prComment

Note: The --prComment flag only works in GitHub Actions when triggered by a pull_request event. It will not create a PR - it only posts comments to existing PRs.

Ready to Get Started?

Add CDK Insights to your pipeline and catch infrastructure issues before they reach production.

View on GitHub CI/CD Integration Guide

Documentation

GitHub Action

Docs Home