Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Tutorial: Environment Promotion

Learn how to safely promote data changes from development through staging to production using Horizon Epoch’s branching model.

Prerequisites

  • Completed Merging Data tutorial
  • Understanding of environment-based workflows

The Environment Branch Model

A typical setup uses long-lived branches for each environment:

production    A---B-----------F---G
                   \         /
staging             C---D---E
                         \
development               H---I---J

Setting Up Environment Branches

1. Create Environment Branches

# Start from main (which represents production)
epoch branch create staging --from main
epoch branch create development --from staging

2. Protect Production

Configure branch protection to prevent direct commits:

epoch branch protect production --require-review --no-force-push

Development Workflow

1. Work on Development

All feature work starts on development or feature branches:

epoch checkout development
epoch branch create feature/new-report --from development

2. Develop and Test

Make changes and commit:

# Make data changes
epoch commit -m "Add sales report aggregations"

3. Merge to Development

epoch checkout development
epoch merge feature/new-report

Promoting to Staging

1. Review Changes

epoch diff staging..development

2. Create a Release Branch (Optional)

For complex releases:

epoch branch create release/v1.2 --from development

3. Promote to Staging

epoch checkout staging
epoch merge development  # or release/v1.2

4. Run Staging Tests

Validate the data in staging environment before proceeding.

Promoting to Production

1. Final Review

epoch diff production..staging

2. Promote to Production

epoch checkout production
epoch merge staging

3. Tag the Release

epoch tag v1.2.0 --message "Release 1.2.0: Sales report aggregations"

Rollback Procedures

Quick Rollback

If issues are found immediately after promotion:

# Revert the last merge
epoch revert HEAD

Rollback to Specific Version

# Find the commit to rollback to
epoch log --oneline -10

# Reset to that commit
epoch reset --hard abc123f

Emergency Production Rollback

# Create a hotfix from the last known good state
epoch checkout production
epoch reset --hard v1.1.0
epoch tag v1.1.1-rollback --message "Emergency rollback from v1.2.0"

Hotfix Workflow

For urgent production fixes:

# 1. Create hotfix from production
epoch branch create hotfix/critical-fix --from production

# 2. Make the fix
epoch checkout hotfix/critical-fix
# ... apply fix ...
epoch commit -m "Fix critical data issue"

# 3. Merge directly to production
epoch checkout production
epoch merge hotfix/critical-fix

# 4. Backport to other environments
epoch checkout staging
epoch merge hotfix/critical-fix

epoch checkout development
epoch merge hotfix/critical-fix

Automation Tips

CI/CD Integration

# Example GitHub Actions workflow
name: Promote to Staging

on:
  workflow_dispatch:
    inputs:
      source_branch:
        description: 'Branch to promote'
        default: 'development'

jobs:
  promote:
    runs-on: ubuntu-latest
    steps:
      - name: Promote to staging
        run: |
          epoch checkout staging
          epoch merge ${{ inputs.source_branch }}
          epoch push

Scheduled Promotions

# Promote development to staging every night
0 2 * * * epoch checkout staging && epoch merge development && epoch push

Best Practices

  1. Never commit directly to production - Always promote through the pipeline
  2. Tag production releases - Makes rollback and auditing easier
  3. Keep environments in sync - Regularly merge production back to development
  4. Automate where possible - Reduces human error
  5. Document promotions - Keep a changelog of what was promoted and when

Next Steps