Skip to main content

​
The Workflow

# 1. Register a component
edgit components add prompt my-prompt components/prompts/analysis.md

# 2. Create a version
edgit tag create my-prompt v1.0.0

# 3. Push tags
edgit push --tags

# 4. Deploy to staging
edgit tag set my-prompt staging v1.0.0
edgit push --tags --force

# 5. Check status
edgit components list
That’s it. Everything else is details. Philosophy: Edgit’s job ends at git push. GitHub Actions handles deployment.

​
Register Components

Tell Edgit what files are components: 
# Register a prompt
edgit components add prompt extraction-prompt components/prompts/extraction.md

# Register a config
edgit components add config api-config components/configs/api.json

# Register a query
edgit components add query analytics-query components/queries/analytics.sql

# Register a script
edgit components add script transform components/scripts/transform.ts
Or discover automatically: 
# Scan for all components
edgit discover scan

# Detect a specific file
edgit discover detect src/my-function.ts
# Output: Type: script, Confidence: 95%

​
Create Versions

Use semantic versioning (v..): 
# Create version tag
edgit tag create my-prompt v1.0.0

# List versions
edgit tag list my-prompt
# Output: v1.0.0, v1.1.0, v1.2.0

# View what changed
git show components/prompts/my-prompt/v1.0.0
Version multiple components: 
edgit tag create extraction-prompt v1.0.0
edgit tag create analysis-config v2.1.0
edgit tag create validation-query v0.5.0
Each component gets its own independent version history. Tags use 4-level format:
  • components/prompts/my-prompt/v1.0.0 (version tag)
  • components/prompts/my-prompt/staging (environment tag)
The prefix (components/prompts/) is automatically inferred from the component type.

​
Deploy to Environment

Mark which versions are deployed to which environments: 
# Deploy to staging
edgit tag set my-prompt staging v1.0.0
edgit push --tags --force

# Test in staging...
# All good? Deploy to production
edgit tag set my-prompt prod v1.0.0
edgit push --tags --force

# Deploy multiple components
edgit tag set extraction-prompt prod v1.0.0
edgit tag set analysis-config prod v2.1.0
edgit push --tags --force
Deployment is just metadata. Edgit creates tags like components/prompts/my-prompt/prod that point to v1.0.0. Your CI/CD reads these tags.

​
When to Use —force

  • Version tags: No --force needed. These are permanent markers. 
    edgit tag create my-prompt v1.0.0
edgit push --tags
  • Environment tags: --force required when moving environments. 
    edgit tag set my-prompt prod v1.0.0
edgit push --tags --force

​
Check Status

See what’s deployed where: 
# Tree view
edgit components list --format tree
# Output:
# extraction-prompt (prompt)
#  v1.0.0 [prod]
#  v0.9.0 [staging]
#  v0.1.0

# Table view
edgit components list --format table
# Output:
# Component         Type    Latest   Prod     Staging
# extraction-prompt prompt  v1.0.0   v1.0.0   v0.9.0
# analysis-config   config  v2.1.0   v2.1.0   v2.0.0

# JSON (for scripts/CI)
edgit components list --format json

​
Rollback

Something broke? Rollback instantly: 
# Rollback to previous version
edgit tag set my-prompt prod v0.9.0
edgit push --tags --force

# Or specific version
edgit tag set my-prompt prod v0.5.0
edgit push --tags --force
Rollback is instant (<50ms globally if you’ve deployed version data to Cloudflare KV).

​
View Versions

See component versions and details: 
# List all versions
edgit tag list my-prompt
# Output: v1.0.0, v0.9.0, v0.8.0

# Show version details
edgit tag show [email protected]
# Shows: commit, author, date, changes

​
Version Agents Too

Agents can be versioned just like components: 
# Register an agent
edgit components add agent scraper agents/scraper/

# Version it
edgit tag create scraper v1.5.0

# Deploy it
edgit tag set scraper prod v1.5.0
edgit push --tags --force

# Now reference in ensembles

agents:
  - name: scraper
    agent: [email protected]  # Locked to specific version

​
Common Patterns

​
Progressive Rollout

# Deploy to staging first
edgit tag set my-prompt staging v2.0.0
edgit push --tags --force

# Test thoroughly...

# Deploy to canary (10% of prod traffic)
edgit tag set my-prompt canary v2.0.0
edgit push --tags --force

# Monitor...

# Full prod rollout
edgit tag set my-prompt prod v2.0.0
edgit push --tags --force

​
A/B Testing

# Deploy variant A
edgit tag set my-prompt prod-variant-a v1.0.0
edgit push --tags --force

# Deploy variant B
edgit tag set my-prompt prod-variant-b v2.0.0
edgit push --tags --force

# Your ensemble references both

agents:
  - name: analyzer-a
    operation: think
    component: [email protected]

  - name: analyzer-b
    operation: think
    component: [email protected]

​
Emergency Rollback

# Production is broken!
# Check available versions
edgit tag list my-prompt

# Rollback to last known good
edgit tag set my-prompt prod v0.9.5
edgit push --tags --force

# Under 50ms later, you're back to working version

​
Use Edgit for All Git Operations

Remember: Edgit is 100% Git-compatible. 
# Use edgit for everything
edgit add .
edgit commit  # AI-powered if OPENAI_API_KEY is set
edgit push
edgit pull
edgit checkout -b feature/new-prompt
edgit merge main

# All git commands work

​
Cheat Sheet

# Register
edgit components add <type> <name> <path>

# Version
edgit tag create <name> <version>
edgit tag list <name>
edgit tag show <name>@<version>

# Deploy
edgit tag set <name> <env> <version>
edgit push --tags --force

# Status
edgit components list
edgit components list --format tree|table|json

# Discover
edgit discover scan
edgit discover scan --type prompt|config|query|script
edgit discover detect <file>

# Standard git (all work with edgit)
edgit add|commit|push|pull|checkout|merge|...

​
Next Steps

Versioning Guide

Deep dive into versioning strategies

Deployment Strategies

Progressive rollouts, A/B testing, canaries

CI/CD Integration

Automate versioning in your pipeline

CLI Reference

Complete command documentation