Understand potentially disruptive Helm chart changes before deployment.

ChartImpact helps teams gain clarity and confidence by surfacing availability, rollout risk, and security changes in Helm chart upgrades. Built with a Go backend using the Helm SDK and a Next.js frontend for a fast, scalable, and maintainable architecture.

ChartImpact provides visibility into Helm chart changes, helping teams understand potential impacts on availability and security before deployment. We focus on surfacing risk signals with clarity—giving teams the information they need to make confident deployment decisions without imposing judgment or automated enforcement.

• 🎯 Impact Summary - Risk-first results view surfaces availability and security risks with contextual explanations
• 🔍 Version Comparison - Compare any two versions (tags, branches, or commits) of a Helm chart
• 📊 Visual Diff Display - Beautiful syntax-highlighted diff output powered by internal diff engine
• 🔬 Interactive Explorer - Structured diff explorer with client-side filtering and search capabilities
• ⚡ Risk Signal Visibility - Understand changes to availability-critical resources (Deployments, StatefulSets, Services)
• 🔐 Security Impact Awareness - Surface changes to security-sensitive configurations (RBAC, NetworkPolicies, ServiceAccounts)
• 🔗 Shareable Links - URL-based sharing enables team collaboration on comparison results
• 💾 Result Storage & Replay - Persistent storage of analysis results with 30-day retention, gzip compression, and hash-based deduplication
• 📈 Analytics Dashboard - Insights into most compared charts, change rates, and deployment risk trends
• 🎨 Modern UI - Clean, responsive interface with mission-aligned design and consistent terminology
• 🚀 Fast & Efficient - Go backend with Helm Go SDK for optimal performance
• 🔧 Flexible - Support for custom values files or inline values content
• 📦 No External Dependencies - Internal diff engine eliminates need for dyff
• 🛡️ Production Ready - Comprehensive error handling, logging, and health checks

• Mission
• Current Features
• Roadmap
• Architecture
• Getting Started
• Usage
• API Reference
• Development
• Deployment
• Contributing
• License

We're working on extending ChartImpact's capabilities to provide earlier feedback in the development workflow:

• Automated GitHub PR Checks (Planned) - Automated analysis of Helm chart changes in pull requests
• CI/CD Integration (Planned) - Early workflow feedback during continuous integration
• Configurable Risk Thresholds (Planned) - Team-defined criteria for highlighting significant changes

These features will maintain our clarity-first philosophy: providing information and visibility without imposing blocking or enforcement mechanisms.

ChartImpact uses a modern separated architecture:

┌─────────────────┐         ┌──────────────────┐
│                 │         │                  │
│  Next.js        │  HTTP   │  Go Backend      │
│  Frontend       ├────────►│  (Port 8080)     │
│  (Port 3000)    ���         │                  │
│                 │         │  - Helm SDK      │
│  - React UI     │         │  - Git Ops       │
│  - TypeScript   │         │  - Internal Diff │
│                 │         │                  │
└─────────────────┘         └──────────────────┘

Backend (/backend):

• Go 1.21+ with Helm Go SDK
• Internal diff engine for fast, deterministic comparisons
• REST API with gorilla/mux
• Structured logging with logrus
• Docker containerized

Frontend (/frontend):

• Next.js 14 with App Router
• TypeScript and React 18
• TailwindCSS for styling
• Docker containerized

The easiest way to run both backend and frontend:

cd ChartImpact

# Start all services (frontend, backend, and PostgreSQL)
docker-compose up

# Access the application
# Frontend: http://localhost:3000
# Backend API: http://localhost:8080
# Health Check: http://localhost:8080/api/health
# Analytics: http://localhost:3000/analytics

The Docker Compose setup includes:

• Frontend (Next.js) on port 3000
• Backend (Go) on port 8080
• PostgreSQL database for result storage and analytics
• Automatic database migrations on startup
• Persistent storage for comparison results

Prerequisites:

• Go 1.21+ - Download
• Node.js 18+ and npm 9+ - Download
• Helm 3.x - Install
• Git

Backend:

cd backend
cp .env.example .env
# Edit .env with your settings
# Required for storage:
#   DATABASE_URL=postgres://chartimpact:chartimpact@localhost:5432/chartimpact?sslmode=disable
#   STORAGE_ENABLED=true
#   RESULT_TTL_DAYS=30
go mod download
go run cmd/server/main.go
# Server runs on http://localhost:8080

Database (PostgreSQL):

# Start PostgreSQL using Docker
docker run -d \
  --name chartimpact-postgres \
  -e POSTGRES_USER=chartimpact \
  -e POSTGRES_PASSWORD=chartimpact \
  -e POSTGRES_DB=chartimpact \
  -p 5432:5432 \
  -v chartimpact_pgdata:/var/lib/postgresql/data \
  postgres:15-alpine

# Run migrations
cd backend/migrations
# Apply migrations in order (001, 002, 003)
psql -h localhost -U chartimpact -d chartimpact -f 001_create_comparisons_table.up.sql
psql -h localhost -U chartimpact -d chartimpact -f 002_create_analytics_view.up.sql
psql -h localhost -U chartimpact -d chartimpact -f 003_create_cleanup_function.up.sql

Frontend:

cd frontend
cp .env.example .env
# Edit .env to set NEXT_PUBLIC_API_URL=http://localhost:8080
npm install
npm run dev
# Frontend runs on http://localhost:3000

ChartImpact provides an interactive web interface for manually inspecting Helm chart changes:

1. Compare Versions - Enter repository details and select two versions to compare
2. Review Changes - Examine differences through the visual diff or Explorer view
3. Understand Impact - Identify changes to availability-critical and security-sensitive resources
4. Share Results - Results are automatically stored with unique URLs for easy sharing
5. Access Analytics - View insights about most compared charts and deployment trends
6. Make Informed Decisions - Use the insights to guide your deployment choices

ChartImpact automatically stores comparison results for 30 days with the following features:

• Automatic Deduplication - Identical comparisons (same repo, chart, versions, values) are stored once
• Compression - Results are gzip-compressed to save storage space (~75% reduction)
• Permalink Access - Each result gets a unique URL (/analysis/{uuid}) for easy sharing
• Expiration Warnings - Visual indicators when results are nearing expiration
• Fresh Re-runs - Option to execute a new comparison with the same parameters

Visit /analytics to view:

• Most compared charts across your organization
• Change rate statistics (percentage of comparisons with changes)
• Average modified resources per comparison
• Deployment risk trends over time

1. Enter the Repository URL (e.g., https://github.com/user/repo.git)
2. Specify the Chart Path (e.g., charts/app)
3. Enter Version 1 (tag, branch, or commit SHA)
4. Enter Version 2 (tag, branch, or commit SHA)
5. (Optional) Provide a values file path or paste values content
6. Click Compare Versions

Repository: https://github.com/myorg/helm-charts.git
Chart Path: charts/myapp
Version 1: v1.0.0
Version 2: v1.1.0
Values File: values/prod.yaml

• Git tags: v1.0.0, 1.2.3, release-2024-01-01
• Branches: main, develop, feature/new-feature
• Commit SHAs: abc123def456...

The Go backend exposes the following REST API endpoints:

Compare two Helm chart versions.

Request Body:

{
  "repository": "https://github.com/argoproj/argo-helm.git",
  "chartPath": "charts/argo-cd",
  "version1": "5.0.0",
  "version2": "5.1.0",
  "valuesFile": "values/production.yaml",  // optional
  "valuesContent": "replicaCount: 3\n",    // optional
  "ignoreLabels": false                     // optional
}

Response:

{
  "success": true,
  "diff": "... internal diff engine output ...",
  "version1": "5.0.0",
  "version2": "5.1.0"
}

Fetch available versions (tags and branches) from a repository.

Request Body:

{
  "repository": "https://github.com/argoproj/argo-helm.git"
}

Response:

{
  "success": true,
  "tags": ["5.1.0", "5.0.0", "4.10.0", ...],
  "branches": ["main", "develop", ...]
}

Health check endpoint.

Response:

{
  "status": "ok",
  "version": "1.0.0",
  "helmOk": true,
  "gitOk": true,
  "dbOk": true
}

Retrieve a stored analysis result by its UUID.

Response:

{
  "success": true,
  "comparison": {
    "success": true,
    "diff": "...",
    "structuredDiff": {...}
  },
  "metadata": {
    "storedAt": "2024-01-15T10:30:00Z",
    "expiresAt": "2024-02-14T10:30:00Z",
    "isExpired": false,
    "isDeduplicated": true,
    "compressionRatio": 0.78
  }
}

List stored analysis results with optional filtering.

Query Parameters:

• repository - Filter by repository URL
• chartPath - Filter by chart path
• since - ISO 8601 timestamp for start date
• until - ISO 8601 timestamp for end date
• limit - Maximum results to return (default: 50)
• offset - Pagination offset (default: 0)

Response:

{
  "success": true,
  "comparisons": [
    {
      "compareId": "uuid",
      "repository": "https://github.com/...",
      "chartPath": "charts/app",
      "version1": "1.0.0",
      "version2": "1.1.0",
      "createdAt": "2024-01-15T10:30:00Z",
      "hasChanges": true,
      "modifiedResourcesCount": 5
    }
  ]
}

Get analytics about most compared charts.

Query Parameters:

• limit - Maximum results to return (default: 10)

Response:

{
  "success": true,
  "popularCharts": [
    {
      "repository": "https://github.com/...",
      "chartPath": "charts/app",
      "comparisonCount": 42,
      "withChanges": 35,
      "avgModifiedResources": 8.5,
      "lastComparisonAt": "2024-01-15T10:30:00Z"
    }
  ],
  "totalComparisons": 150,
  "periodStart": "2023-10-17T00:00:00Z",
  "periodEnd": "2024-01-15T10:30:00Z"
}

For detailed API documentation, see backend/README.md.

• Node.js: 18.0.0 or higher
• npm: 9.0.0 or higher
• Helm: 3.x (must be installed and available in PATH)
• Git: For cloning repositories

macOS:

brew install helm

Linux:

curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

Windows:

choco install kubernetes-helm

The easiest way to deploy both backend and frontend together:

docker-compose up -d

See docker-compose.yml for configuration details.

The frontend can be deployed to Cloudflare Pages. You'll need to deploy the backend separately.

Build Settings:

• Framework preset: Next.js
• Build command: npm run build
• Build output directory: .next
• Root directory: frontend

Environment Variables:

NEXT_PUBLIC_API_URL=https://your-backend-api.example.com

See frontend/CLOUDFLARE_PAGES.md for detailed instructions.

Build and run individual services:

# Build backend
cd backend
docker build -t chartimpact-backend .
docker run -p 8080:8080 chartimpact-backend

# Build frontend
cd frontend
docker build -t chartimpact-frontend .
docker run -p 3000:3000 -e NEXT_PUBLIC_API_URL=http://localhost:8080 chartimpact-frontend

This project includes GitHub Actions workflows for testing and maintaining code quality:

• CI Pipeline (ci.yml): Runs backend and frontend tests, linting, and builds on every PR
• Frontend Tests (frontend-tests.yml): Comprehensive frontend testing including unit, integration, and E2E tests
• Release Workflow (release.yml): Creates releases and builds Docker images when version tags are pushed
• CodeQL Analysis (codeql.yml): Security scanning for vulnerabilities

See .github/workflows/README.md for detailed documentation.

Note: These workflows are for maintaining ChartImpact itself. Integration of ChartImpact as an automated check in your own GitHub PRs is a planned feature.

ChartImpact/
├── backend/                   # Go backend API
│   ├── cmd/server/           # Application entry point
│   ├── internal/             # Internal packages
│   │   ├── api/             # HTTP handlers and middleware
│   │   ├── diff/            # Internal diff engine
│   │   ├── service/         # Business logic (Helm operations)
│   │   └── models/          # Data types and schemas
│   ├── Dockerfile           # Backend container
│   └── go.mod               # Go dependencies
├── frontend/                 # Next.js frontend
│   ├── app/                 # Next.js app directory
│   │   ├── api/            # API routes (proxy to backend)
│   │   ├── demo/           # Demo page
│   │   └── page.tsx        # Main comparison page
│   ├── components/          # React components
│   │   ├── explorer/       # Explorer v2 components
│   │   └── __tests__/      # Component tests
│   ├── e2e/                # End-to-end tests (Playwright)
│   ├── Dockerfile          # Frontend container
│   └── package.json        # Frontend dependencies
├── .github/workflows/       # CI/CD automation
├── docker-compose.yml       # Multi-service deployment
└── README.md               # This file

• npm run dev - Start development server
• npm run build - Build for production
• npm start - Start production server
• npm run lint - Run ESLint
• npm run type-check - Run TypeScript type checking
• npm test - Run tests
• npm run test:watch - Run tests in watch mode
• npm run test:coverage - Generate test coverage report

Backend Environment Variables:

# Storage Configuration (optional, disabled by default)
STORAGE_ENABLED=true                    # Enable result storage and replay
DATABASE_URL=postgres://user:pass@host:port/dbname?sslmode=disable
DB_MAX_CONNECTIONS=25                   # Maximum database connections
RESULT_TTL_DAYS=30                      # Days to retain stored results

# Other Configuration
HELM_TIMEOUT=30000                      # Helm operation timeout (milliseconds)
LOG_LEVEL=info                          # Log level (debug, info, warn, error)

Frontend Environment Variables:

Create a .env.local file for local development:

# Backend API URL
NEXT_PUBLIC_API_URL=http://localhost:8080

ChartImpact includes an optional PostgreSQL-based storage system for persisting analysis results:

Features:

• 30-day retention with automatic cleanup
• Gzip compression (~75% size reduction)
• Hash-based deduplication (identical comparisons stored once)
• Async storage (doesn't slow down comparisons)
• Analytics for popular charts and trends

To Enable Storage:

1. Set environment variables:

   STORAGE_ENABLED=true
   DATABASE_URL=postgres://chartimpact:chartimpact@localhost:5432/chartimpact?sslmode=disable
   RESULT_TTL_DAYS=30

2. Run database migrations (automatically applied with Docker Compose):

   cd backend/migrations
   psql -h localhost -U chartimpact -d chartimpact -f 001_create_comparisons_table.up.sql
   psql -h localhost -U chartimpact -d chartimpact -f 002_create_analytics_view.up.sql
   psql -h localhost -U chartimpact -d chartimpact -f 003_create_cleanup_function.up.sql

3. (Optional) Schedule cleanup job:

   -- Manual cleanup
   SELECT delete_expired_comparisons();
   
   -- Or use pg_cron for automatic cleanup
   SELECT cron.schedule('cleanup-expired', '0 2 * * *', 
     'SELECT delete_expired_comparisons()');

Storage is optional - ChartImpact works perfectly without it, but you'll miss out on result replay and analytics features.

For more details, see STORAGE_SPEC.md.

Ensure Helm is installed and available in your PATH:

which helm
helm version

• Verify the repository URL is correct and accessible
• Check network connectivity
• Ensure the repository is public or credentials are configured

• Verify the chart path exists in the repository
• Check that the specified version contains the chart
• Ensure the path is relative to the repository root

• Large repositories may take time to clone
• Consider using shallow clones for faster performance
• Check system resources (CPU, memory, disk)

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

• Helm - The package manager for Kubernetes
• Next.js - The React framework
• React Syntax Highlighter - Syntax highlighting

• 🐛 Report a bug
• 💡 Request a feature
• 💬 Start a discussion

Made with ❤️ for the Kubernetes and Helm community