Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ensemble.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Understanding Deployment in Edgit

Deployment in Edgit is just metadata. When you “deploy,” you’re creating a Git tag that points to a version: 
# Create version tag
edgit tag create prompts/extraction v1.0.0
edgit push --tags

# Deploy to production (set environment slot)
edgit tag set prompts/extraction production v1.0.0
edgit push --tags --force
Tags use the 4-level format: {prefix}/{type}/{name}/{slot} where slots are environments like staging, production, or canary. Edgit’s job ends at git push. Your CI/CD (GitHub Actions) reads these tags, syncs to Cloudflare KV, and triggers rebuilds. This means:
  • Deployments are instant (just Git tags)
  • Rollbacks are instant (update the tag)
  • You can deploy different versions to different environments simultaneously
  • Perfect audit trail (Git history)

​
Strategy 1: Traditional (Staging → Production)

The safe, predictable approach.

​
Workflow

# 1. Create version
edgit tag create prompts/extraction v1.1.0
edgit push --tags

# 2. Deploy to staging
edgit tag set prompts/extraction staging v1.1.0
edgit push --tags --force

# 3. Test in staging
curl https://staging.example.com/test

# 4. Promote to production
edgit tag set prompts/extraction production v1.1.0
edgit push --tags --force
Note: Version tags (v1.1.0) don’t need --force. Environment tags (staging, production) need --force because they move between versions. When to use: Most production systems, especially when starting out Pros:
  • Simple to understand
  • Clear separation of environments
  • Easy to test before production
Cons:
  • Slower (requires testing in each environment)
  • Staging might not catch all issues (different data, traffic patterns)

​
Strategy 2: Canary Deployments

Deploy to a small percentage of production traffic first.

​
Setup

# Create version
edgit tag create prompts/extraction v1.1.0
edgit push --tags

# Deploy to production and canary
edgit tag set prompts/extraction production v1.0.0
edgit tag set prompts/extraction canary v1.1.0
edgit push --tags --force

​
Workflow

# 1. Deploy new version to canary (10% traffic)
edgit tag set prompts/extraction canary v1.1.0
edgit push --tags --force

# 2. Monitor canary
# Watch error rates, latency, user feedback

# 3. If good, promote to production
edgit tag set prompts/extraction production v1.1.0
edgit push --tags --force

​
Configure Traffic Splitting

In your Conductor ensemble: 
ensemble: canary-example

agents:
  # 90% get stable version
  - name: analyzer-stable
    operation: think
    component: prompts/extraction@production
    condition: ${Math.random() < 0.9}

  # 10% get canary version
  - name: analyzer-canary
    operation: think
    component: prompts/extraction@canary
    condition: ${Math.random() >= 0.9}

output:
  result: ${analyzer-stable.output || analyzer-canary.output}
  was_canary: ${analyzer-canary.executed}
When to use: High-traffic systems where you need confidence before full rollout Pros:
  • Test with real production traffic
  • Catches issues that staging misses
  • Can roll back without affecting everyone
Cons:
  • More complex setup
  • Need monitoring to detect issues
  • Some users get different versions

​
Strategy 3: Blue-Green Deployment

Run two complete environments, switch instantly.

​
Setup

# Create version
edgit tag create prompts/extraction v1.1.0
edgit push --tags

# Blue environment (current production)
edgit tag set prompts/extraction blue v1.0.0
edgit push --tags --force

# Green environment (new version)
edgit tag set prompts/extraction green v1.1.0
edgit push --tags --force

​
Workflow

# 1. Test green thoroughly
curl https://green.example.com/test

# 2. Switch production traffic to green
# Update load balancer / DNS to point to green

# 3. Keep blue running for quick rollback

# 4. After confirming green is stable, update blue
edgit tag set prompts/extraction blue v1.1.0
edgit push --tags --force
When to use: When you need instant rollback without affecting users Pros:
  • Zero-downtime deployments
  • Instant rollback (switch back to blue)
  • Can test green with production-like environment
Cons:
  • Requires double the infrastructure
  • More expensive
  • Need to keep data in sync between blue/green

​
Strategy 4: Feature Flags / A/B Testing

Deploy multiple versions, control who gets what.

​
Setup

ensemble: ab-test-example

agents:
  # Control group (50% of users)
  - name: analyzer-control
    operation: think
    component: prompts/extraction@v1.0.0
    condition: ${input.user_id % 2 === 0}

  # Treatment group (50% of users)
  - name: analyzer-treatment
    operation: think
    component: prompts/extraction@v1.1.0
    condition: ${input.user_id % 2 === 1}

output:
  result: ${analyzer-control.output || analyzer-treatment.output}
  variant: ${analyzer-control.executed ? 'control' : 'treatment'}

​
Workflow

# 1. Deploy both versions as environment slots
edgit tag set prompts/extraction control v1.0.0
edgit tag set prompts/extraction treatment v1.1.0
edgit push --tags --force

# 2. Collect metrics from both
# Track success rates, user satisfaction, performance

# 3. Pick winner
edgit tag set prompts/extraction production v1.1.0
edgit push --tags --force
When to use: When you want to measure impact objectively Pros:
  • Data-driven decisions
  • Can test multiple variants
  • Users get consistent experience (sticky sessions)
Cons:
  • Need analytics infrastructure
  • Requires statistical significance
  • More complex to set up

​
Strategy 5: Progressive Rollout

Gradually increase percentage over time.

​
Workflow

# Day 1: Deploy to 1%
edgit tag create prompts/extraction v1.1.0
edgit push --tags
edgit tag set prompts/extraction rollout-1pct v1.1.0
edgit push --tags --force

# Day 2: Increase to 10%
edgit tag set prompts/extraction rollout-10pct v1.1.0
edgit push --tags --force

# Day 3: Increase to 50%
edgit tag set prompts/extraction rollout-50pct v1.1.0
edgit push --tags --force

# Day 4: Full rollout
edgit tag set prompts/extraction production v1.1.0
edgit push --tags --force

​
Configure Gradual Rollout

ensemble: progressive-rollout

agents:
  # Use new version based on percentage
  - name: analyzer
    operation: think
    component: >
      ${Math.random() * 100 < env.ROLLOUT_PERCENTAGE
        ? 'prompts/extraction@v1.1.0'
        : 'prompts/extraction@v1.0.0'}
When to use: When you want fine-grained control over rollout speed Pros:
  • Can pause at any percentage
  • Easy to roll back (decrease percentage)
  • Gradual impact on systems
Cons:
  • Requires feature flag infrastructure
  • More complex than binary on/off

​
Strategy 6: Ring Deployment

Deploy to concentric “rings” of users.

​
Ring Structure

# Ring 0: Internal team
edgit tag set prompts/extraction ring-0 v1.1.0
edgit push --tags --force

# Ring 1: Beta users
edgit tag set prompts/extraction ring-1 v1.1.0
edgit push --tags --force

# Ring 2: Early adopters (10%)
edgit tag set prompts/extraction ring-2 v1.1.0
edgit push --tags --force

# Ring 3: General users (remaining 90%)
edgit tag set prompts/extraction ring-3 v1.0.0
edgit push --tags --force
When to use: Large user bases with different risk tolerances Pros:
  • Very safe (catch issues early with small groups)
  • Can get feedback from beta users
  • Clear rollout plan
Cons:
  • Slowest approach
  • Need user segmentation
  • Complex configuration

​
Combining Strategies

Real-world: combine multiple strategies.

​
Example: Staged Canary Rollout

# Stage 1: Dev testing
edgit tag set prompts/extraction dev v1.1.0
edgit push --tags --force

# Stage 2: Staging with production data
edgit tag set prompts/extraction staging v1.1.0
edgit push --tags --force

# Stage 3: Production canary (5%)
edgit tag set prompts/extraction canary-5 v1.1.0
edgit push --tags --force

# Stage 4: Increase canary (25%)
edgit tag set prompts/extraction canary-25 v1.1.0
edgit push --tags --force

# Stage 5: Full rollout
edgit tag set prompts/extraction production v1.1.0
edgit push --tags --force

​
Rollback Strategies

Every deployment strategy needs a rollback plan.

​
Instant Rollback

# Something's wrong! Roll back to previous version
edgit tag set prompts/extraction production v1.0.0
edgit push --tags --force

# Under 50ms later (if using Cloudflare KV), you're back
Remember: --force is required for environment tags because you’re moving the tag to point to a different version.

​
Blue-Green Rollback

# Switch traffic back to blue
# Update load balancer to point to blue environment

# Instant rollback, zero downtime

​
Best Practices

​
1. Start Conservative

# Do: Start with smallest possible audience
edgit tag set prompts/extraction canary-1 v1.1.0
edgit push --tags --force

# Don't: YOLO full production
edgit tag set prompts/extraction production v1.1.0
edgit push --tags --force

​
2. Have a Rollback Plan

# Do: Document rollback command
# If issues: edgit tag set prompts/extraction production v1.0.0

# Don't: Deploy without knowing how to undo

​
3. Use —force for Environment Tags

# Version tags: No --force needed
edgit tag create prompts/extraction v1.1.0
edgit push --tags

# Environment tags: Require --force
edgit tag set prompts/extraction production v1.1.0
edgit push --tags --force

​
4. Let CI/CD Handle the Rest

# Edgit's job ends at git push
edgit push --tags --force

# GitHub Actions:
# - Reads tags
# - Updates Cloudflare KV
# - Triggers rebuilds
# - Sends notifications

​
Next Steps

Rollback & Time Travel

Emergency rollbacks and debugging

A/B Testing

Multivariate testing strategies

CI/CD Integration

Automate deployments in your pipeline

Versioning Guide

Master component and agent versioning