chore: optimize deployment to trigger only on version tags

[victorbruce]

🎯 What This PR Does

Optimizes the deployment workflow to trigger only on version tags, eliminating redundant deployments and providing explicit control over production releases.

❌ Current Problem

Double deployments for every feature:

1. Merge PR to main
   → Deployment #1 triggered (feature code)

2. Run: npm run release:patch
   → Creates commit: "chore(release): 1.0.1"

3. Run: git push --follow-tags origin main
   → Deployment #2 triggered (same code + version bump)

Result: 2 deployments for essentially the same code

Issues:

• ❌ Wastes CI/CD minutes (50% redundant)
• ❌ Unnecessary Render build time
• ❌ Multiple deployment events for one feature
• ❌ No explicit control over when production deploys

✅ Solution

Deploy only on version tags:

1. Merge PR to main
   → No deployment (code merged, not deployed)

2. Run: npm run release:patch
   → Creates commit + tag: v1.0.1

3. Run: git push --follow-tags origin main
   → Single deployment triggered by tag

Result: 1 deployment per release ✅

🔄 Changes Made

Updated deploy-render.yml:

Before:

on:
  push:
    branches:
      - main

After:

on:
  push:
    tags:
      - 'v*'  # Only deploy on version tags
  workflow_dispatch:  # Manual deployment still possible

Added Features:

• ✅ Version extraction from tags
• ✅ Automatic GitHub Release creation
• ✅ Enhanced deployment verification
• ✅ Deployment summary with version tracking

🚀 New Deployment Workflow

For Feature Development:

# 1. Develop feature
git checkout -b feat/add-angular-material
git commit -m "feat: add Angular Material"
git push origin feat/add-angular-material

# 2. Create PR and merge to main
# → No deployment triggered (code merged only)

# 3. When ready to release:
git checkout main
git pull origin main

# 4. Create release
npm run release  # Auto-detects version bump from commits
# Creates: commit + tag (e.g., v1.1.0)

# 5. Push with tags
git push --follow-tags origin main
# → Deployment triggered by tag ✅
# → GitHub Release created automatically ✅

For Hotfixes:

# Same process but with patch bump
npm run release:patch  # v1.0.0 → v1.0.1
git push --follow-tags origin main

📊 Impact Analysis

CI/CD Minutes Saved:

Metric	Before	After	Savings
Deploys per feature	2	1	50%
Monthly deploys (est. 10 features)	20	10	50%
CI minutes/month (5 min/deploy)	100 min	50 min	50 min saved

Render Deployments:

Before:

✅ Deploy: feat/add-material merged
❌ Deploy: chore(release): 1.1.0 (redundant)

After:

✅ Deploy: v1.1.0 tagged (single deployment)

💡 Benefits

1. Explicit Control

• Deploy only when you create a release
• No accidental production deployments
• Clear intention: tag = production release

2. Cost Efficiency

• 50% fewer CI/CD minutes used
• 50% fewer Render build minutes
• Lower resource consumption

3. Semantic Clarity

Tags = Versions = Releases = Deployments

v1.0.0 → Production release #1
v1.1.0 → Production release #2
v2.0.0 → Production release #3

4. Easy Rollbacks

# Current broken version: v1.1.0
# Rollback to previous version:
git tag  # Find stable version (v1.0.0)

# Option A: Revert and release
git revert <commit-hash>
npm run release:patch
git push --follow-tags origin main

# Option B: Redeploy old tag (if needed)
# Manually trigger workflow_dispatch with v1.0.0

5. Clean Deployment History

GitHub Releases:
- v1.0.0 (Dec 22) - Initial production release
- v1.0.1 (Dec 23) - Add standard-version
- v1.1.0 (Dec 24) - Add Angular Material
- v1.1.1 (Dec 25) - Bug fixes

Each release = one deployment

6. Automatic GitHub Releases

• Release notes extracted from CHANGELOG.md
• Automatic release creation on tag push
• Version tracking in GitHub Releases page

🧪 Testing Plan

Test 1: Push to Main Without Tag

git checkout main
echo "test" >> README.md
git commit -m "docs: update readme"
git push origin main

Expected: ❌ No deployment triggered ✅

Test 2: Push with Version Tag

npm run release:patch
git push --follow-tags origin main

Expected: 
✅ Deployment triggered by tag
✅ GitHub Release created
✅ Render deploys

Test 3: Manual Deployment

# In GitHub Actions → Deploy to Render → Run workflow
# Select: workflow_dispatch

Expected: ✅ Manual deployment works

📝 Migration Notes

For Existing Workflows:

No breaking changes - your workflow stays the same, just more efficient:

# Still works exactly as before:
npm run release
git push --follow-tags origin main

# But now:
# - Only ONE deployment (not two)
# - Triggered by the tag (not the commit)
# - GitHub Release created automatically

For Emergency Deploys:

If you need to deploy without a release:

# Option 1: Create a release tag
npm run release:patch
git push --follow-tags origin main

# Option 2: Manual workflow dispatch
# GitHub → Actions → Deploy to Render → Run workflow

🎓 What This Teaches

This optimization demonstrates:

• ✅ Professional CI/CD practices
• ✅ Cost-conscious engineering
• ✅ Semantic versioning alignment
• ✅ Explicit vs implicit automation
• ✅ Production deployment best practices

Industry standard: Most professional projects deploy on tags, not every commit.

🔍 Observability

How to Monitor:

GitHub:

• Actions tab → Deploy to Render workflow
• Only runs on tag pushes
• Each run shows version being deployed

Render:

• Dashboard → Events
• Deployment triggered by: "Deploy Hook"
• One deployment per tag

GitHub Releases:

• Releases tab
• Automatic release for each version
• Changelog extracted and formatted

✅ Success Criteria

After merge:

• Push to main without tag → No deployment
• Push with tag → Deployment triggered
• GitHub Release created automatically
• Render deployment successful
• Only one deployment per release
• Workflow dispatch still works

📚 Documentation Updates

README.md section added:

### Deployment

This project uses tag-based deployments:

1. Merge features to main (no deployment)
2. Create release: `npm run release`
3. Push with tags: `git push --follow-tags origin main`
4. Deployment triggered automatically by tag

🎯 Summary

Problem: Redundant deployments waste resources
Solution: Deploy only on version tags
Impact: 50% fewer deployments, explicit control
Benefit: Professional workflow, cost-efficient

---

This optimization aligns our deployment strategy with industry best practices while saving CI/CD resources. 🚀

🔗 Related

• Semantic Versioning: https://semver.org/
• GitHub Releases: https://docs.github.com/en/repositories/releasing-projects-on-github
• standard-version: https://github.com/conventional-changelog/standard-version