Skip to main content
Skip to main content

GitHub Integration

Automatically create GitHub issues from CDK Insights findings to streamline your development workflow and ensure security issues are tracked and resolved.

Why Use GitHub Integration?

Automated Issue Tracking

Security findings are automatically converted into actionable GitHub issues with detailed descriptions and remediation steps.

Team Collaboration

Issues can be assigned to team members, discussed, and tracked through your existing GitHub workflow.

Audit Trail

Maintain a complete history of security issues and their resolution status in your repository.

Integration with CI/CD

Seamlessly integrate with your existing CI/CD pipelines and development processes.

Setup Guide

1

Generate GitHub Token

Create a personal access token with repository permissions

GitHub → Settings → Developer settings → Personal access tokens

Important: Use fine-grained tokens for better security control

2

Set GitHub Token

Set your GitHub token as an environment variable

# Add to your shell profile (~/.bashrc or ~/.zshrc) export GITHUB_TOKEN=ghp_your_token_here # Or set for current session export GITHUB_TOKEN=ghp_your_token_here

Important: Never commit tokens to version control - always use environment variables

3

Run Analysis with GitHub Integration

Execute CDK Insights with markdown output and GitHub flag

npx cdk-insights scan --output markdown --withIssue

Important: Requires GitHub CLI (gh) to be installed and authenticated

4

Review Created Issues

Check your GitHub repository for newly created issues

GitHub → Issues → Check for newly created issue

Important: Issues include full markdown report with detailed findings and remediation steps

Configuration Options

GITHUB_TOKEN

Requiredenvironment variable

GitHub personal access token with repository permissions

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

--output markdown

RequiredCLI flag

Must use markdown output format for GitHub integration

--output markdown

--withIssue

RequiredCLI flag

Enable GitHub issue creation

--withIssue

GitHub CLI (gh)

Requiredtool dependency

GitHub CLI must be installed and authenticated

gh auth login

Issue Templates

Critical Severity Template

Issue Title:

🔴 Critical Security Issue: {issue}

Issue Body:

## CDK Insights Finding

**Severity:** Critical
**Service:** {service}
**Resource:** {resource}

### Description
{description}

### Impact
This issue poses a significant security risk and should be addressed immediately.

### Recommended Fix
```typescript
{fix}
```

### References
- [AWS Security Best Practices](https://docs.aws.amazon.com/security/)
- [CDK Security Guidelines](https://docs.aws.amazon.com/cdk/latest/guide/security.html)

---
*This issue was automatically created by CDK Insights*

High Severity Template

Issue Title:

🟠 High Priority: {issue}

Issue Body:

## CDK Insights Finding

**Severity:** High
**Service:** {service}
**Resource:** {resource}

### Description
{description}

### Impact
This issue should be addressed in the current development cycle.

### Recommended Fix
```typescript
{fix}
```

### Next Steps
1. Review the recommended fix
2. Test the changes in a development environment
3. Deploy the fix to production

---
*This issue was automatically created by CDK Insights*

Best Practices

Use Environment Variables

Store GitHub tokens securely using environment variables

export GITHUB_TOKEN="ghp_your_token_here"

Why: Prevents accidental exposure in version control

Install GitHub CLI

Ensure GitHub CLI is installed and authenticated

gh auth login

Why: Required for automatic issue creation from CDK Insights

Use Fine-Grained Tokens

Create GitHub tokens with minimal required permissions

Permissions: Issues (write), Repository metadata (read)

Why: Follows principle of least privilege for better security

Always Use Markdown Output

GitHub integration requires markdown output format

npx cdk-insights scan --output markdown --withIssue

Why: Markdown format provides properly formatted issue content

Troubleshooting

❌ "GitHub token invalid or expired"

Verify your token has the correct permissions and hasn't expired. Create a new token if necessary.

❌ "Repository not found"

Check the repository name format is correct (owner/repo) and that your token has access to the repository.

❌ "Issues not being created"

Ensure findings meet the configured severity threshold and that the createIssues option is set to true.

❌ "Rate limit exceeded"

GitHub has rate limits for API calls. Consider reducing the frequency of scans or using a GitHub App instead of a personal token.

Ready to Integrate with GitHub?

Start creating GitHub issues automatically from your CDK Insights findings to improve your security workflow.

Configuration GuideCI/CD Integration