Phase H: Environments - Deployment Management

Overview

Phase H implements GitHub Environments for development, staging, and production with environment-specific secrets and deployment protection rules.

Status

• Status: Complete
• Priority: Medium
• Duration: 1 hour (simplified from 3h estimate)
• Agent: DeploymentAgent

GitHub as OS Mapping

GitHub Environments → Environment Isolation
- Development → Dev Environment
- Staging → QA Environment
- Production → Production Environment
- Protection Rules → Access Control

Goals and Objectives

Primary Goals

1. Create 3 environments (dev, staging, production)
2. Configure environment-specific secrets
3. Implement deployment protection rules
4. Enable manual approval workflows
5. Ensure environment isolation

Success Metrics

• All 3 environments configured
• Secrets properly isolated
• Protection rules enforced
• Manual approvals required for production
• Zero unauthorized deployments

Implementation Details

1. Environment Definitions

Environments Created:

• development - Auto-deploy on feature branch push
• staging - Manual approval required (1 reviewer)
• production - Manual approval required (2 reviewers)

Configuration via GitHub UI:

Repository → Settings → Environments → New environment

2. Environment Secrets

Each environment has isolated secrets:

# development
GITHUB_TOKEN: dev_token
ANTHROPIC_API_KEY: dev_key
DATABASE_URL: dev_db_url

# staging
GITHUB_TOKEN: staging_token
ANTHROPIC_API_KEY: staging_key
DATABASE_URL: staging_db_url

# production
GITHUB_TOKEN: prod_token
ANTHROPIC_API_KEY: prod_key
DATABASE_URL: prod_db_url

3. Deployment Workflow

File: .github/workflows/deploy-environments.yml

name: Deploy to Environment

on:
  push:
    branches: [main, staging, develop]
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environment to deploy'
        required: true
        type: choice
        options:
          - development
          - staging
          - production

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment || 'development' }}
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Deploy to ${{ inputs.environment }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          echo "Deploying to ${{ inputs.environment }}..."
          npm run deploy:${{ inputs.environment }}

      - name: Notify deployment
        run: |
          echo "✅ Deployed to ${{ inputs.environment }}"

4. Protection Rules

Staging Environment

• Wait timer: 5 minutes
• Required reviewers: 1
• Allowed branches: staging, main
• Required checks: tests, build

Production Environment

• Wait timer: 30 minutes
• Required reviewers: 2
• Prevent self-review: Enabled
• Allowed branches: main only
• Required checks: tests, build, security-scan

Configuration via GitHub UI:

Environment → Protection rules → Add rule

Completion Criteria and KPIs

Acceptance Criteria

Key Performance Indicators

Implementation Steps

Step 1: Create Environments

# Via GitHub UI: Settings → Environments → New environment
# Create: development, staging, production

Step 2: Configure Secrets

For each environment:

Environment → Secrets → Add secret

Step 3: Set Protection Rules

Staging:

• Required reviewers: 1
• Wait timer: 5 minutes

Production:

• Required reviewers: 2
• Wait timer: 30 minutes
• Prevent self-review: Yes

Step 4: Test Deployment

# Trigger manual deployment
gh workflow run deploy-environments.yml -f environment=staging

# Check deployment status
gh run list --workflow=deploy-environments.yml

Testing Methodology

Test Development Deployment

# Should deploy automatically
git push origin develop

Test Staging Deployment

# Should require 1 approval
gh workflow run deploy-environments.yml -f environment=staging

# Approve via GitHub UI
# Repository → Actions → Select run → Review deployments

Test Production Deployment

# Should require 2 approvals
gh workflow run deploy-environments.yml -f environment=production

# Requires 2 different reviewers to approve

Troubleshooting Guide

Issue: Deployment Stuck Waiting

Solutions:

1. Check required approvals configured
2. Verify reviewers have permission
3. Check wait timer not exceeded
4. Review deployment logs

Issue: Secrets Not Available

Solutions:

1. Verify secret name matches exactly
2. Check environment name correct
3. Ensure secret added to correct environment
4. Test with workflow dispatch

Configuration Reference

Branch to Environment Mapping

# Automatic deployment mapping
develop → development
staging → staging
main → production (with approval)

Environment Variables

# Available in workflow
${{ inputs.environment }}      # Selected environment
${{ secrets.GITHUB_TOKEN }}    # Environment-specific token
${{ secrets.ANTHROPIC_API_KEY }}  # Environment-specific API key

References and Resources

Official Documentation

• GitHub Environments
• Deployment Protection Rules

Credits

Implemented by: DeploymentAgent Issue: #5 Phase H Model: Claude Sonnet 4 Date: 2025-10-08 Duration: 1 hour

Status: ✅ Complete Next Phase: Phase I - Releases