Skip to main content

Release Process

This document describes the complete release process for manufacturing-admin, from creating a release to deploying to production.

Overview​

The manufacturing-admin release process follows a "build once, deploy many" pattern with three GitHub Actions workflows:

  1. Tag & Build - Automatically triggered when creating a pre-release
  2. Deploy to Production (Specific Tag) - Manual deployment with a specific tag
  3. Deploy to Production (Latest) - Manual deployment with the latest tag

Why Pre-Releases?​

We create GitHub pre-releases (not full releases) when tagging to:

  • Keep the release in draft state until deployed to production
  • Prevent confusion about which version is actually live
  • Allow the "Deploy Latest" workflow to mark it as the official release after successful deployment

Prerequisites​

  • Access to the GitHub repository
  • Permission to push tags to the repository
  • Access to manually trigger GitHub Actions workflows

Complete Release Flow​

Step 1: Create a Pre-Release on GitHub​

Version tags must follow semantic versioning: v\{MAJOR\}.\{MINOR\}.\{PATCH\}

  1. Go to GitHub → Releases → Draft a new release
  2. Click "Choose a tag"
  3. Type your new version tag (e.g., v1.2.3) and select "Create new tag on publish"
  4. Select the target branch (usually main)
  5. Enter release title (e.g., v1.2.3)
  6. Check "Set as a pre-release" ✅
  7. Click "Publish release"

What happens automatically:

  • ✅ CI/CD checks run (Biome, TypeScript, Tests)
  • ✅ Docker image is built
  • ✅ Image is tagged with the version (e.g., web-portal:v1.2.3)
  • ✅ Image is pushed to production registry: registry.digitalocean.com/manufacturing-admin-production
  • ✅ AI-generated release notes are created
  • ✅ GitHub release is updated with formatted notes
  • ✅ Slack notification posted to #infra-releases with release summary

Important:

  • This creates a pre-release (not marked as latest)
  • This does NOT deploy to any environment
  • The Docker image is ready in the registry for deployment

Step 2: Deploy to Production​

You have two options for deploying to production:

  1. Go to GitHub Actions → Release tag to Production
  2. Click "Run workflow"
  3. Enter the tag you want to deploy (e.g., v1.2.3)
  4. Click "Run workflow"

What happens:

  • ✅ Checks if this is a rollback (deploying older version)
  • ✅ Runs CI/CD checks on the tag
  • ✅ Runs database migrations on production database
  • ✅ Seeds reference tables
  • ✅ Updates app spec to use the specified image tag
  • ✅ Deploys to production: https://mes.birdygrey.com
  • ✅ Posts deployment notification to #infra-releases
    • Shows rollback warning if deploying older version
    • Includes link to production site

Option B: Deploy Latest Tag​

  1. Go to GitHub Actions → Release latest tag to Production
  2. Click "Run workflow"
  3. Click "Run workflow" (no input needed - auto-detects latest tag)

What happens:

  • ✅ Automatically detects the latest tag
  • ✅ Runs CI/CD checks on the tag
  • ✅ Runs database migrations on production database
  • ✅ Seeds reference tables
  • ✅ Updates app spec to use the latest image tag
  • ✅ Deploys to production: https://mes.birdygrey.com
  • ✅ Marks GitHub release as "published" and "latest" (removes pre-release status)
  • ✅ Posts deployment notification to #infra-releases

Note: This workflow will convert your pre-release into a full release and mark it as the latest.

Rollback Process​

To rollback to a previous version:

  1. Use Option A (Deploy a Specific Tag)
  2. Enter the tag of the version you want to rollback to (e.g., v1.2.2)
  3. The workflow will detect this is a rollback and notify in Slack

Note: The rollback detection compares commit dates. If the tag you're deploying is older than the current latest release, it will be flagged as a rollback.

Release Notes​

Release notes are automatically generated using AI (Claude) and include:

  • Categorized changes: Bug Fixes, Features, Dependencies, etc.
  • Linear ticket links: Automatically converted (e.g., INFRA-123 → Linear link)
  • GitHub PR links: With proper formatting
  • Contributor mentions: GitHub usernames → Slack mentions
  • Dependency updates: Grouped together at the bottom

Release notes are posted to:

  • Slack #infra-releases channel (Slack markdown format)
  • GitHub release page (GitHub markdown format)

Workflow Files​

  • .github/workflows/deploy-qa.yml - Tag & Build workflow
  • .github/workflows/release-tag-production.yml - Deploy specific tag
  • .github/workflows/release-latest-production.yml - Deploy latest tag

Environment Configuration​

Staging Environment​

Staging Container Image Management​

Staging uses a tag rotation strategy to maintain rollback capability while automatically cleaning up old images:

Tag Rotation Flow:

  1. :candidate - New image is built and pushed with this tag
  2. :staging - The :candidate is promoted to :staging (active deployment), then :candidate is deleted
  3. :previous - The old :staging is re-tagged as :previous (rollback target)
  4. Garbage collection - Untagged images are automatically cleaned up

Rollback: The :previous tag enables rollback to the last deployed version. However, the next push to main will automatically deploy new code again, so rollback is temporary unless commits are reverted in the main branch.

Registry: registry.digitalocean.com/manufacturing-admin-staging

Production Environment​

  • Trigger: Manual workflow dispatch
  • URL: https://mes.birdygrey.com
  • Database: Separate production database with firewall protection
  • Registry: registry.digitalocean.com/manufacturing-admin-production

Best Practices​

  1. Always test in staging first before creating a production tag
  2. Use semantic versioning for tags (v{MAJOR}.{MINOR}.{PATCH})
  3. Always create as pre-release when tagging (not full release)
  4. Review AI-generated release notes in Slack before deploying
  5. Deploy during maintenance windows for major releases
  6. Use "Deploy Latest" workflow to mark releases as official after successful deployment
  7. Verify production after deployment using the "View Production" link in Slack

Troubleshooting​

Tag workflow failed​

  • Check GitHub Actions logs for the specific failure
  • Common issues:
    • Tests failing
    • Docker build errors
    • Registry authentication issues

Production deployment failed​

  • Check if database migrations succeeded
  • Verify app spec was updated correctly
  • Check DigitalOcean App Platform logs

Rollback needed urgently​

  • Use the rollback process above
  • The previous Docker image is still in the registry and can be deployed immediately

Questions?​

For questions about the release process, reach out in #infra-releases on Slack.