Step 1 · Prepare Deployment

Goal

Validate that the application is ready to deploy — artefacts built, environment configuration verified, rollback plan confirmed, and the team notified — so that the deploy itself is low-risk and reversible.

Instructions

You are in workflow step 1 of the deploy-cycle. Preparation eliminates the most common causes of failed deployments: wrong environment variables, unbuilt assets, missing migrations, and no rollback route.

Tasks to Perform

1. Verify CI Green

# Confirm the latest commit passed all checks before deploying
gh run list --branch main --limit 5
# or
gh run view <RUN_ID>

# All of these must be green:
# ✅ Unit & integration tests
# ✅ Lint / type-check
# ✅ Security scan
# ✅ Build artefact

Do not deploy from a commit with failing or skipped checks.

2. Build and Tag the Release Artefact

# Build the deployable artefact
docker build -t myapp:$(git rev-parse --short HEAD) .
docker tag myapp:$(git rev-parse --short HEAD) myapp:latest

# Push to registry
docker push registry.example.com/myapp:$(git rev-parse --short HEAD)
docker push registry.example.com/myapp:latest

# For non-container apps
npm run build:production
tar -czf release-$(date +%Y%m%d-%H%M).tar.gz dist/

# Tag the git commit
VERSION=$(cat VERSION)   # or derive from package.json / composer.json
git tag -a "v${VERSION}" -m "Release v${VERSION}"
git push origin "v${VERSION}"

3. Validate Environment Configuration

# Compare required .env keys against target environment
# List required keys
grep -E "^[A-Z_]+" .env.example | cut -d= -f1 | sort > required-keys.txt

# List keys in production (using your secrets manager CLI)
# AWS SSM:
aws ssm get-parameters-by-path --path "/myapp/prod/" --query "Parameters[].Name" \
  | jq '.[]' | sed 's|.*/||' | sort > prod-keys.txt

# GitHub Secrets (if deploying via Actions):
gh secret list | cut -d' ' -f1 | sort > prod-keys.txt

diff required-keys.txt prod-keys.txt
# If diff is non-empty → no-go until resolved

4. Review Pending Database Migrations

# Check which migrations are unapplied in production
# Laravel
php artisan migrate:status --env=production

# Alembic (Python)
alembic history --indicate-current

# Flyway
flyway -url=jdbc:... info

# Rules:
# ✅ All pending migrations are backwards-compatible with current code
# ✅ No column drops or renames without a 2-phase migration plan
# ✅ Large table migrations have an online-alter strategy (pt-online-schema-change, gh-ost)

5. Write the Deployment Runbook Entry

Create or update docs/deploy/runbook.md:

## Deploy — vX.Y.Z — YYYY-MM-DD

### What's changing
- Feature: ...
- Fix: ...
- Migrations: yes/no — files: [list]

### Risk assessment
- [ ] Low  [ ] Medium  [ ] High — reason: ...

### Rollback plan
1. Roll back container: `kubectl rollout undo deployment/myapp` (takes ~60s)
2. Revert DB migration: `php artisan migrate:rollback --step=1`
3. Verify: smoke test URLs listed below

### Smoke test URLs
- GET /api/health → 200
- GET /api/v1/products → 200, array not empty
- POST /api/v1/auth/login with test-user → 200 with token

6. Notify the Team

# Post a deploy notice in your team chat channel:
#   • What is deploying (version, key changes)
#   • When (window start time)
#   • Who is the deployer and on-call contact
#   • Rollback owner if something goes wrong

# Then set application to maintenance mode if the deploy requires it
php artisan down --secret="bypass-token-here"
# (allows the deployer to browse the site while others see maintenance page)

Exit Criteria

  • [ ] Latest CI run on deploy branch is fully green
  • [ ] Docker image (or release tarball) built and pushed to registry
  • [ ] Image/artefact tagged with the git SHA or version
  • [ ] All target-environment secrets/vars verified to be set
  • [ ] Pending DB migrations reviewed and cleared as safe
  • [ ] Rollback plan documented in runbook
  • [ ] Team notified of upcoming deploy

Next Step

→ Proceed to Step 2 · Deploy and Verify