Diverge

Branch your infrastructure, not just your code.

Environment-as-a-service engine for Kubernetes. Diverge creates ephemeral preview environments with async routing, Prometheus observability, GitLab support, SDK propagation, and configurable database provisioning. Extensible via a pluggable provider registry.

Get Started

curl -fsSL https://raw.githubusercontent.com/divergedev/diverge/main/install.sh | sh

Documentation: https://divergedev.com

• Multi-User Dev & Conflict Detection (Pro)
• Feature Flags Guide
• Hot Reload Guide
• Observability Guide
• MCP Server Guide
• CLI Reference
• Topology & Route Simulation
• Header Propagation

Try It

5-minute demo → — Multi-repo preview environments with k3d + Envoy Gateway. Features a complete hands-on bank-demo showcasing database schema isolation and automated migration jobs!

Quick Start

You can quickly test Diverge locally with the CLI:

diverge dev --service my-app

Helm Install

helm install diverge oci://ghcr.io/divergedev/charts/diverge --version <version>

See charts/diverge/values.yaml for configuration options.

Key Features

• PreviewGroup Orchestration: Manage multiple child environments and services under a single CR tied directly to an MR/PR. Automatic orphan cleanup and label-based ownership.
• Provider Registry: Pluggable, extensible architecture — add new routing, deployer, notifier, or database providers with a single file. Zero changes to the controller.
• Scale-to-Zero: Idle preview environments automatically scale to zero via KEDA HTTP Add-on (HTTPScaledObject). The interceptor wakes up pods on the first request, resulting in 90%+ resource savings for idle MRs.
• Activator Proxy: Smart routing that directs traffic to the pod when ready. Includes X-Preview-Env header injection and a shared informer for efficient pod state tracking.
• Delta Deployment: Only deploy what changed, falling back to a baseline for unmodified services.
• Header-Based Routing & Gateway API: Leverages Gateway API, Istio, and the Diverge Proxy to route traffic seamlessly using HTTP headers.
• Configurable DB Modes: Options for shared, schema, snapshot, or fresh databases for your environments.
• Schema-per-Environment: Actual execution of SQL-based schema provisioning (via SQLExecutor), regex-validated naming, injection prevention, and automated migration Jobs.
• MR-Triggered Lifecycle: Environments spin up when a Merge Request opens and tear down upon merge/close.
• Merge Gating: GitLab/GitHub commit status checks (diverge/preview) block merges until environments are healthy.
• Argo CD & Direct Deploy: Argo CD GitOps (Application CRs) and No-ArgoCD mode (DirectDeployer) for Helm charts and Kustomize overlays.
• Feature Flags & OpenFeature: Isolated flag evaluation per preview environment. Out-of-the-box support for in-cluster flagd ConfigMaps and remote Flipt ephemeral namespaces with automated cleanup on MR merge.
• Environment Export: diverge env export extracts environment variables from preview pods for local development (dotenv, JSON, shell formats).
• Test Integration: CI trigger and polling support to run automated tests against preview environments.
• Prometheus Metrics: Reconciliation duration, deployment status, route counts, active environments, and preview group gauges.
• Namespace Labels: Custom labels on preview namespaces (e.g., istio.io/dataplane-mode: ambient for zero-trust mTLS).
• Security Hardened: Webhook secret constant-time comparison, RFC 7230 header validation, safe SHA handling, ArgoCD namespace bypass prevention, IPv6-safe pod URLs, typed Server-Side Apply (SSA), and strict label validation.
• Finalizer-Based Lifecycle: Kubernetes finalizers ensure clean teardown of all resources (routing, database, ArgoCD apps) even during force-deletes.
• TTL Auto-Expiry: Automatic environment cleanup after configurable TTL with requeue-based expiry.
• Multi-SCM Notifiers: GitLab MR comments and GitHub PR comments with status updates.
• E2E Tested: Dual-cluster end-to-end tests with k3d, Envoy Gateway, and real CRD reconciliation.
• ConnectRPC API Server: Opt-in API server (server.enabled: true in Helm) featuring ConnectRPC (HTTP/1.1 + HTTP/2, browser-native, curlable), OIDC JWT + K8s TokenReview authentication, namespace-scoped RBAC authorization, structured audit logging, list pagination, optimistic concurrency, and CORS for browser/SPA clients.
• Service Topology & Route Simulation: diverge route <service> traces request paths through your service graph. diverge graph show renders the topology as Mermaid, DOT, or JSON.
• Changed-Service Detection: diverge diff identifies which services are affected by your code changes using git diff + path-based service mapping. Outputs JSON for CI integration.
• Prometheus Topology Discovery: Auto-discovers service dependencies from Istio, Linkerd, or Cilium mesh metrics. Background cache with stale-while-revalidate for zero-latency CLI responses.

Async Routing

Diverge provides fully isolated preview environments for asynchronous workloads.

• Subdomain vs Header Routing: Use mode: subdomain for frontend-to-backend workflows without passing custom headers.
• Available Providers: Supported provisioners include Temporal, Kafka, Noop, and Webhook.
• Slim Builds: Use no_temporal and no_kafka build tags for smaller binaries.

See the Async Routing Guide for full configuration details and YAML examples.

Security

Diverge takes security seriously. The platform features strict CRD OpenAPI validation, context timeouts on all external calls, and prevention mechanisms for shell/markdown injection in templates. The controller uses RBAC-scoped clients to ensure it only has the permissions it needs. Webhook interactions are secured using constant-time comparisons for secrets and RFC 7230-compliant header validation. Recent hardening includes ArgoCD namespace bypass prevention, safe SHA handling to eliminate panics, IPv6-safe pod URLs, comprehensive label validation, and Typed Server-Side Apply (SSA) to ensure safe resource updates.

• Container images are signed with cosign using keyless (OIDC) identity
• Every release includes an SBOM (SPDX) attached to the container image
• CRD YAML bundles are published as release artifacts
• Helm chart is published to oci://ghcr.io/divergedev/charts
• GitHub Actions are pinned to commit SHAs

Architecture

Diverge consists of 4 main components compiled into a single consolidated Docker image (ghcr.io/divergedev/diverge:latest), released via goreleaser:

1. Controller (diverge-controller): The Kubernetes operator that watches for PreviewGroup and Environment Custom Resources (CRs), reconciles them, and provisions the necessary resources (like Argo CD Application CRs, databases, etc.).
2. Proxy (diverge-proxy): A reverse proxy that helps facilitate header-based routing to preview environments.
3. Activator (diverge-activator): A proxy for scale-to-zero workloads. Wakes up sleeping pods on the first request and seamlessly routes traffic once they are ready.
4. CLI (diverge): A powerful CLI to interact with Diverge environments directly from your terminal.

PreviewGroup Example

A minimal PreviewGroup Custom Resource managing multiple services for a single MR:

apiVersion: divergedev.com/v1alpha1
kind: PreviewGroup
metadata:
  name: mr-42
spec:
  source:
    provider: gitlab
    project: myorg/platform
    branch: feat/payments
  routing:
    headerKey: x-preview-env
    headerValue: "42"
  services:
    - name: payments-api
      image: registry.example.com/payments:mr-42
      mode: image
      port: 8080
    - name: gateway
      mode: baseline

CLI Commands

The diverge CLI helps you manage environments efficiently:

• diverge init - Initialize a .diverge.yaml config
• diverge create - Create a new environment
• diverge list - List active environments
• diverge status - Check the status of an environment
• diverge open - Open the preview URL in your browser
• diverge logs - Stream logs for a preview environment
• diverge dev - Local development mode with preview routing
• diverge env export - Export environment variables (dotenv, JSON, shell)
• diverge mcp - Run MCP server over stdio for AI agent integration
• diverge preview - Create preview environments from CLI
• diverge validate - Validate your .diverge.yaml
• diverge delete - Delete an environment
• diverge version - Show CLI version

Installation

Install via shell script:

curl -fsSL https://divergedev.com/install.sh | sh

Or download and verify first:

curl -fsSL -o install.sh https://divergedev.com/install.sh
sha256sum install.sh  # verify contents
sh install.sh

Or install via Go:

go install github.com/divergedev/diverge/cmd/diverge@v0.8.0

Install via Helm (Kubernetes Operator)

helm repo add diverge https://divergedev.github.io/diverge
helm repo update
helm install diverge diverge/diverge --namespace diverge-system --create-namespace

Docker Images (for reference)

The controller and proxy images are available at:

docker pull ghcr.io/divergedev/diverge:v0.8.0

Or download the binary from Releases.

Development

Diverge requires Go 1.26+. The project uses Nix to manage development dependencies.

# Enter the Nix development shell
nix develop

# Apply CRDs and run locally
nix develop -c make install
nix develop -c make run

Currently, the project contains 943 tests utilizing table-driven tests, testify/assert, and Property-Based Testing (PBT) using the Hegel framework (hegel.dev/go/hegel).

Roadmap

• Provider Registry — Pluggable provider architecture with generic Registry[T]
• Environment Export — diverge env export for local dev workflows
• E2E Tests — Dual-cluster k3d tests with Envoy Gateway
• Prometheus Metrics — Reconciliation, deployment, routing metrics
• Godoc Coverage — 80%+ documentation on exported symbols
• GitLab/GitHub Commit Statuses — Merge gating via diverge/preview commit status checks
• Schema-per-Environment — SQL-based schema provisioning with SchemaProvider
• Proto Foundation — Protobuf domain types + ConnectRPC service definition
• Async Router — Kafka, Temporal, and Webhook providers with KEDA auto-scaling and SDK helpers
• Subdomain Routing — Browser-accessible frontend preview environments via wildcard DNS
• Slim Build — Build tags (no_knative, no_schema, no_temporal, no_kafka) for smaller binaries
• ConnectRPC API Server (#12) — gRPC/ConnectRPC API server for environment management
• WebSocket Support (#6) — WebSocket proxy routing via Gateway API HTTPRoute with path matching and configurable timeouts
• gRPC Routing — Gateway API GRPCRoute generation for gRPC services (protocol: grpc)

License

Apache 2.0