Environment Synchronization

Environment synchronization enables controlled promotion of secrets between environments (e.g., staging to production) with approval gates and audit trails.

Overview

Environment sync provides:

Controlled promotion: Staging → Production with approval
Approval gates: Required reviewers before sync
Diff preview: See changes before applying
Audit trail: Complete sync history
Rollback: Revert to previous state

Use Cases

Staging to Production

Promote tested configuration to production:

Test changes in staging environment
Request sync to production
Approver reviews diff
Approver approves sync
Production updated

Development to Staging

Share new configuration:

Add new variables in development
Sync to staging for testing
Automatic sync (if configured)
Team notified of changes

Multi-Environment Consistency

Keep environments in sync:

Configure automatic sync rules
Changes propagate automatically
Notifications sent to team
Audit log tracks all changes

Configuration

Web Interface

Go to Project Settings → Sync
Click Add Sync Rule
Configure:
- Source environment (e.g., staging)
- Target environment (e.g., production)
- Sync mode (manual or automatic)
- Require approval (yes/no)
- Approvers (if approval required)
Save

CLI

# Create sync configuration
dotvault sync config my-project \
  --from staging \
  --to production \
  --mode manual \
  --require-approval \
  --approvers user1@example.com,user2@example.com

# List sync configurations
dotvault sync list my-project

# Request sync
dotvault sync request my-project --from staging --to production

# Approve sync (as approver)
dotvault sync approve my-project --sync-id sync_xxx

# Reject sync
dotvault sync reject my-project --sync-id sync_xxx --reason "Need to test more"

# Execute sync (after approval)
dotvault sync execute my-project --from staging --to production

# View sync history
dotvault sync history my-project

API

# Create sync configuration
POST /api/projects/{projectId}/sync-configs
{
  "sourceEnvLabel": "staging",
  "targetEnvLabel": "production",
  "syncMode": "manual",
  "requireApproval": true,
  "approvers": ["user_xxx", "user_yyy"]
}

Response:
{
  "data": {
    "id": "sync_xxx",
    "sourceEnvLabel": "staging",
    "targetEnvLabel": "production",
    "syncMode": "manual",
    "requireApproval": true,
    "approvers": ["user_xxx", "user_yyy"],
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

# Request sync
POST /api/projects/{projectId}/sync-requests
{
  "syncConfigId": "sync_xxx"
}

Response:
{
  "data": {
    "id": "req_xxx",
    "syncConfigId": "sync_xxx",
    "requesterUserId": "user_zzz",
    "status": "pending_approval",
    "diff": {
      "totalChanges": 3,
      "additions": 1,
      "updates": 1,
      "deletions": 1,
      "changes": [
        {
          "key": "NEW_VAR",
          "action": "add",
          "sourceValue": "new_value",
          "targetValue": ""
        },
        {
          "key": "EXISTING_VAR",
          "action": "update",
          "sourceValue": "new_value",
          "targetValue": "old_value"
        },
        {
          "key": "OLD_VAR",
          "action": "delete",
          "sourceValue": "",
          "targetValue": "value_to_remove"
        }
      ]
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

# Approve sync
POST /api/projects/{projectId}/sync-requests/{requestId}/approve

Response:
{
  "data": {
    "id": "req_xxx",
    "status": "approved",
    "approvedByUserId": "user_xxx",
    "approvedAt": "2024-01-15T10:35:00Z"
  }
}

# Execute sync
POST /api/projects/{projectId}/sync-requests/{requestId}/execute

Response:
{
  "data": {
    "id": "req_xxx",
    "status": "completed",
    "executedAt": "2024-01-15T10:36:00Z",
    "appliedChanges": 3
  }
}

Sync Modes

Manual Sync

Requires explicit request and approval:

User requests sync
Diff generated and shown
Approver reviews
Approver approves
Sync executed

Best for: Production environments, sensitive changes

Automatic Sync

Syncs immediately on source changes:

Source environment updated
Diff generated automatically
Sync executed immediately
Notification sent

Best for: Development → Staging, non-sensitive environments

Pull Request Mode

Creates a "PR" for review:

User requests sync
Diff generated
PR created in GitHub/GitLab
Team reviews and approves
Sync executed on merge

Best for: Teams using Git-based workflows

Approval Workflow

Requesting Sync

Requester:

Select source and target environments
Review generated diff
Add optional comment
Submit request

Reviewing Sync

Approver sees:

Side-by-side diff
Change summary (add/update/delete counts)
Requester and timestamp
Optional comment

Approval Options

Approver can:

Approve: Sync proceeds
Reject: Sync cancelled with reason
Request Changes: Send back for modification

Multiple Approvers

Configure multiple required approvers:

{
  "requireApproval": true,
  "approvers": ["user_xxx", "user_yyy", "user_zzz"],
  "requiredApprovals": 2
}

Diff Preview

Change Types

Action	Icon	Description
Add	+	New variable in target
Update	~	Variable value changed
Delete	-	Variable removed from target
Unchanged	=	No change

Diff Display

Sync Preview: staging → production

Additions (1):
+ NEW_API_KEY = sk_***...***

Updates (1):
~ DATABASE_URL
  - postgres://old-host:5432/db
  + postgres://new-host:5432/db

Deletions (1):
- DEPRECATED_VAR = value

Unchanged (12):
= STRIPE_KEY = sk_***...***
= JWT_SECRET = ***...***
...

Value Masking

Sensitive values are masked in diff:

API keys: sk_***...***
Passwords: ***
URLs: postgres://***:***@host/db

Notifications

Requester Notifications

Submitted: Confirmation with diff link
Approved: Ready to execute
Rejected: With reason
Executed: Completion confirmation

Approver Notifications

Pending: New sync request
Reminder: If not reviewed (12 hours)
Executed: After completion

Team Notifications

Slack: Posted to configured channel
Email: Summary to project members
Audit Log: All events recorded

Best Practices

1. Always Use Approval for Production

Require approval for production syncs:

{
  "sourceEnvLabel": "staging",
  "targetEnvLabel": "production",
  "requireApproval": true,
  "approvers": ["tech-lead@company.com", "devops@company.com"]
}

2. Review Diff Carefully

Before approving, check:

All additions are intentional
Updates are correct
Deletions won't break anything
No secrets exposed in diff

3. Test in Staging First

Always test changes:

Update development environment
Sync to staging automatically
Test thoroughly in staging
Request sync to production
Approve after verification

4. Document Sync Decisions

Add comments explaining syncs:

Request: "Adding new payment provider configuration"
Approval: "Tested in staging, looks good"

5. Monitor Sync Activity

Regular reviews:

# Weekly sync review
dotvault sync history my-project --from 2024-01-01 --to 2024-01-31

# Check for rejected syncs
dotvault sync history my-project --status rejected

6. Use Consistent Naming

Standard environment names:

development or dev
staging or stage
production or prod

Makes sync rules clearer and reduces errors.

Rollback

Automatic Backup

Before sync, target environment is backed up:

Current state saved as version
Sync applied
Can restore if issues

Manual Rollback

If sync causes issues:

# View sync history
dotvault sync history my-project

# Find previous version
dotvault versions list my-project --env production

# Restore previous version
dotvault versions restore my-project --env production --version 5

Rollback Notifications

All rollbacks trigger:

Urgent notifications
Audit log entries
Incident flagging

Troubleshooting

Sync Request Not Received

Check approver email addresses
Verify approvers have access
Check notification settings
Review spam folders

Cannot Approve Sync

Verify you're in approvers list
Check sync is still pending
Ensure you have project access
Contact project owner

Sync Failed

Check diff for conflicts
Verify target environment exists
Check permissions
Review error logs
Retry or rollback

Conflicts Detected

If target changed since diff generated:

Sync request invalidated
New diff generated
Re-approval required
Prevents overwriting changes

Compliance

Regulatory Requirements

Environment sync helps meet:

SOX: Change control procedures
HIPAA: Access controls
PCI DSS: Configuration management
SOC 2: Change management

Audit Trail

All sync events logged:

Sync requested
Diff generated
Approval/rejection
Sync executed
Rollback (if any)

Retention: 7 years

API Reference

Update Sync Config

PATCH /api/projects/{projectId}/sync-configs/{configId}
{
  "requireApproval": true,
  "approvers": ["user_xxx", "user_yyy"],
  "isActive": true
}

Response:
{
  "data": {
    "id": "sync_xxx",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Delete Sync Config

DELETE /api/projects/{projectId}/sync-configs/{configId}

Response:
{
  "data": {
    "success": true
  }
}

Get Sync Status

GET /api/projects/{projectId}/sync-configs/{configId}/status

Response:
{
  "data": {
    "id": "sync_xxx",
    "status": "active",
    "lastSyncAt": "2024-01-15T10:30:00Z",
    "lastSyncStatus": "completed",
    "pendingApprovals": 0
  }
}

Pricing

Sync features by plan:

Feature	Free	Pro	Enterprise
Manual sync	✓	✓	✓
Automatic sync	-	✓	✓
Approval gates	-	✓	✓
Multiple approvers	-	-	✓
Sync history	30 days	90 days	Unlimited
GitHub PR mode	-	-	✓

Support

Documentation: https://docs.dotvault.io/sync
Community: https://community.dotvault.io
Email: support@dotvault.io

Overview​

Use Cases​

Staging to Production​

Development to Staging​

Multi-Environment Consistency​

Configuration​

Web Interface​

CLI​

API​

Sync Modes​

Manual Sync​

Automatic Sync​

Pull Request Mode​

Approval Workflow​

Requesting Sync​

Reviewing Sync​

Approval Options​

Multiple Approvers​

Diff Preview​

Change Types​

Diff Display​

Value Masking​

Notifications​

Requester Notifications​

Approver Notifications​

Team Notifications​

Best Practices​

1. Always Use Approval for Production​

2. Review Diff Carefully​

3. Test in Staging First​

4. Document Sync Decisions​

5. Monitor Sync Activity​

6. Use Consistent Naming​

Rollback​

Automatic Backup​

Manual Rollback​

Rollback Notifications​

Troubleshooting​

Sync Request Not Received​

Cannot Approve Sync​

Sync Failed​

Conflicts Detected​

Compliance​

Regulatory Requirements​

Audit Trail​

API Reference​

Update Sync Config​

Delete Sync Config​

Get Sync Status​

Pricing​

Support​