> ## 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.

# Deployment Strategies

> Deploy with confidence: progressive rollouts, canaries, blue-green, A/B testing. Roll back instantly.

## Understanding Deployment in Edgit

**Deployment in Edgit is just metadata.** When you "deploy," you're creating a Git tag that points to a version:

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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:

```yaml theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
# 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

```yaml theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
# 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

```yaml theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# Switch traffic back to blue
# Update load balancer to point to blue environment

# Instant rollback, zero downtime
```

## Best Practices

### 1. Start Conservative

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# Edgit's job ends at git push
edgit push --tags --force

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Rollback & Time Travel" icon="clock-rotate-left" href="/edgit/guides/rollback-time-travel">
    Emergency rollbacks and debugging
  </Card>

  <Card title="A/B Testing" icon="flask" href="/edgit/guides/ab-testing-multivariate">
    Multivariate testing strategies
  </Card>

  <Card title="CI/CD Integration" icon="workflow" href="/edgit/getting-started/cicd-integration">
    Automate deployments in your pipeline
  </Card>

  <Card title="Versioning Guide" icon="tags" href="/edgit/guides/versioning-components-agents">
    Master component and agent versioning
  </Card>
</CardGroup>