Skip to main content

ADR 0003: Promotion Gates

Status​

Accepted

Context​

Production promotions must require human approval while keeping development and staging environments automated for rapid feedback.

The requirements include:

  • Automated deployments to dev and staging for fast iteration
  • Manual approval required for production changes
  • Clear audit trail of who approved production deployments
  • Emergency override capability for critical fixes
  • Integration with existing GitHub workflows

Decision​

Use GitHub Environments with required reviewers for production deployments. Staging promotions are automated after smoke checks.

Environment Configuration​

  • Dev Environment: No approval required, deploys automatically on ops repo merge
  • Staging Environment: Automatic promotion after dev smoke tests pass
  • Production Environment: Requires manual approval from designated reviewers

Approval Workflow​

  1. PR merged to ops repo triggers dev deployment
  2. Smoke tests run in dev environment
  3. If smoke tests pass, staging deployment triggers automatically
  4. For production, deployment pauses and requests approval
  5. Designated approvers review change and approve/reject
  6. On approval, production deployment proceeds

Consequences​

Positive​

  • The prod environment requires explicit human approval
  • Staging promotions are performed by CI after successful smoke tests
  • Rollbacks are executed by git revert or tag rollback in ops repo
  • Clear audit trail via GitHub's deployment history
  • Prevents accidental production deployments
  • Maintains fast feedback loop for dev/staging

Negative​

  • Production deployments are slower due to manual gate
  • Requires designation and training of production approvers
  • Emergency deployments still require approval (by design)

Neutral​

  • Approval SLA should be defined (e.g., 2-hour response time during business hours)
  • Off-hours approval process needs to be documented
  • Emergency override process should be documented but restricted

Implementation​

GitHub Environment Configuration​

# .github/workflows/deploy.yml
jobs:
  deploy-prod:
    environment:
      name: production
      url: https://app.example.com
    steps:
      - name: Deploy to Production
        run: ./deploy-prod.sh

Repository Settings​

  • Navigate to Settings > Environments > Production
  • Add required reviewers (minimum 1, recommended 2)
  • Enable "Prevent administrators from bypassing required reviews" (optional)
  • Set deployment branch pattern (e.g., main only)

Rollback Strategy​

Rollbacks are git operations, not approval-gated:

  • Immediate rollback: Git revert in ops repo + fast-track approval
  • Tag rollback: Update ops repo to point to previous tag
  • Emergency: Designated approvers can fast-track emergency fixes