Intelligent Branch Routing & Auto-Preview Environments

Overview

Feature #1421 introduces a fully automated preview environment system. Instead of manually configuring staging servers or managing complex routing rules, .git now intercepts push events to non-default branches and automatically provisions isolated environments with unique subdomains.

This feature is designed to eliminate "works on my machine" syndrome, accelerate code review cycles, and reduce infrastructure overhead by automatically tearing down unused environments after 7 days of inactivity.

How It Works

When a developer pushes to a feature branch, .git executes the following pipeline:

1. Branch Detection: The webhook listener identifies the target branch and checks against your environment rules.
2. Isolation Provisioning: A dedicated container/VPC slice is allocated with fresh environment variables and database snapshots.
3. Dynamic Routing: DNS records are automatically provisioned using pattern matching (e.g., feat-1421.git.app).
4. Health Check & Notification: Once the build passes and the service responds to health checks, a comment is posted to the associated PR with the preview URL.

Configuration

Preview environments are configured via .git/config.yaml at the root of your repository. You can define build commands, resource limits, environment variables, and lifecycle rules.

YAML Syntax

preview:
  # Enable/disable auto-preview
  enabled: true
  # Branch patterns to trigger environments
  branches:
    - "feature/*"
    - "feat-*    - "bugfix/*"
  # Resource allocation per environment
  resources:
    cpu: "1000m"
    memory: "512Mi"
  # Lifecycle management
  lifecycle:
    auto_destroy: true
    inactivity_timeout: "7d"
    on_merge: "teardown"

Environment Triggers

You can override default triggers using environment variables in your CI context or via the .git dashboard:

• PASSWORD_PROTECTED=true - Require basic auth for the preview URL
• DB_SNAPSHOT=latest - Restore from the most recent production backup
• SKIP_HEALTH_CHECK=true - Bypass readiness probes (not recommended)

Known Limitations

While #1421 is production-ready, please note the following constraints during the current rollout phase:

• Maximum of 50 concurrent preview environments per repository on the Starter tier.
• Dynamic DNS propagation may take up to 30 seconds in edge regions outside of AWS us-east-1.
• Database snapshots are read-only by default to prevent accidental data mutations. Use DB_WRITE_ACCESS=true to enable writes.
• Custom domains require manual DNS verification and are not supported on auto-teardown instances.

Examples

Node.js / Express

{
  "scripts": {
    "dev": "node server.js",
    "start": "node server.js",
    "preview": "node server.js --port=$PORT --env=$GIT_PREVIEW_ENV"
  }
}

Python / FastAPI

# Injected automatically by .git runtime
PORT=8080
DATABASE_URL=postgresql://preview-db.internal/snapshot_latest
APP_ENV=preview

Changelog

• v2.4.1 (Oct 2025) - Fixed DNS race condition on rapid branch switches
• v2.4.0 (Sep 2025) - Initial release of Feature #1421
• v2.3.9 (Aug 2025) - Added YAML validation schema for .git/config.yaml