Skip to main content
DRAFT

​
Deployment Process

Our application uses a custom branching and deployment strategy with Vercel.

​
Branch Structure

  • main: Source of truth, always deployable
  • rc/1.XX.X: Release candidates for testing
  • release/1.XX: Production releases
  • stage: Used to trigger staging deployment (cona.run)
  • prod: Used to trigger production deployment (cona.app)

​
Versioning

The project adheres to Semantic Versioning (SemVer) standards, with version numbers structured as MAJOR.MINOR.PATCH:
  • MAJOR: Incompatible API changes
  • MINOR: Backward-compatible functionality additions
  • PATCH: Backward-compatible bug fixes

​
Monorepo Versioning Strategy

Our monorepo uses a simplified versioning approach:
  • apps/webapp/package.json: Contains the main project version (e.g., 0.6.0)
  • Internal packages (packages/*): No version fields - they’re private internal libraries
  • apps/temporal-workers: Separate deployment artifact with its own version
This approach focuses version management on the main deliverable (the webapp) while keeping internal packages simple and dependency-free.

​
Environments

  • Development: Automatically deployed from main (Preview deployments)
  • Staging: Automatically deployed when changes are pushed to stage branch, deployed to https://cona.run
  • Production: Automatically deployed when changes are pushed to prod branch, deployed to https://cona.app

​
Infrastructure Components

Each environment includes multiple components that are automatically deployed: Web Application (Vercel)
  • Staging: https://cona.run
  • Production: https://cona.app
Temporal Workers (fly.io)
  • Staging: Deployed using apps/temporal-workers/fly.staging.toml configuration
  • Production: Deployed using apps/temporal-workers/fly.prod.toml configuration
Database Migrations (Supabase)
  • Executed via GitHub Actions with environment-specific variables
  • Environment variables configured in GitHub repository settings

​
Workflow

​
Feature Development

  1. Create feature branches from main
  2. Merge completed features to main
  3. Automatic deployment to development environment

​
Release Process

The release process is now automated through GitHub Actions, supporting three types of releases: Major, Minor, and Patch. The workflow automatically handles version bumping, branch creation, and PR generation.
Automated Release Workflow
  1. Trigger the “Create RC and Release Branches” workflow from GitHub Actions
  2. Select the release type:
    • Major: Increments the major version (e.g., 0.5.3 → 1.0.0)
    • Minor: Increments the minor version (e.g., 0.5.3 → 0.6.0)
    • Patch: Increments the patch version (e.g., 0.5.3 → 0.5.4)
The workflow will automatically:
  • Read the current version from apps/webapp/package.json
  • Calculate the next version based on the release type
  • Create appropriate branches:
    • For Major/Minor: Creates rc/x.y.z from main and release/x.y from latest release
    • For Patch: Creates rc/x.y.z from the existing release branch
  • Update version in apps/webapp/package.json
  • Create a PR from RC to release branch
Release Testing and Deployment
  1. Automatic deployment to RC Environments in Vercel (staging)
  2. If issues are found in RC:
    • Fix them in main
    • Cherry-pick fixes to RC: git cherry-pick -x <commit-hash> (use -x to include the original commit message)
  3. Once the RC branch is fully tested, merge the PR to the release branch

​
Hotfixes (Existing Release)

  1. Trigger the “Create RC and Release Branches” workflow
  2. Select “Patch” as the release type
  3. The workflow will:
    • Create an RC branch from the existing release branch
    • Update the patch version in apps/webapp/package.json
    • Create a PR from RC to release branch
  4. Fix any issues in main
  5. Cherry-pick needed fixes to RC: git cherry-pick -x <commit-hash>
  6. Once the RC branch is fully tested, merge the PR to the release branch

​
Deployment to production

Run “Create PR from latest release to prod” GitHub action to open the PR from the latest release to prod branch. Merge to prod branch automatically starts deployment to Vercel’s production environment (cona.app).

​
Testing and Fixes

  1. Test the RC in staging
  2. If issues are found, fix them in main
  3. Cherry-pick fixes to RC: git cherry-pick -x <commit-hash>

​
Promoting to Production

​
Automated Deployment Process

Vercel (Web Application) Automatically deployed on branch changes: fly.io (Temporal Workers) After cutover, .github/workflows/deploy-workers.yml deploys on pushes when repository variable WORKERS_GHA_DEPLOY is true:
  • stage uses apps/temporal-workers/fly.staging.toml, the staging environment secret FLY_API_TOKEN_WORKERS_STAGING, and --ha=false.
  • prod uses apps/temporal-workers/fly.prod.toml and the Production environment secret FLY_API_TOKEN_WORKERS_PROD, retaining Fly HA.
Freeze prod merges during cutover. Before enabling the variable: restrict Production to prod only and staging to stage only (remove release/*, rc/* and any other branches), disable native Fly GitHub auto-deploy for both worker apps, then configure those environment secrets. Set WORKERS_GHA_DEPLOY to true and check that the production image’s build.commit matches the frozen prod head; trigger a push/current-head workflow or an authorized deployment of that head if needed, and verify the label before unfreezing. Push to stage and verify its image’s build.commit matches the triggering SHA. See deployment identity and cutover for prerequisites, rerun guards and image rollback. Manual package deploy scripts bypass this workflow and omit commit stamping. Database Migrations (Supabase) Executed via GitHub Actions:
  • Migrations are executed automatically as part of the deployment process
  • Environment-specific variables are configured in GitHub repository settings
  • Supports both staging and production database environments
Note: Vercel deployments remain managed through its GitHub integration. Worker deployments use the gated GitHub Actions workflow after cutover; keep native Fly GitHub auto-deploy disabled to avoid duplicate rollouts. Database migrations run independently of worker deployment.

​
Automated Version Management

Version numbers are automatically managed through GitHub Actions workflows. Only the main project version in apps/webapp/package.json is managed - internal packages (packages/*) have no version fields and don’t require version synchronization.

​
Version Workflow

  1. Creating Releases - Use the “Create RC and Release Branches” GitHub Action:
    • Automatically reads current version from apps/webapp/package.json
    • Calculates new version based on release type (Major/Minor/Patch)
    • Creates RC branch with updated version
    • Creates PR from RC to release branch
  2. Automatic Version Synchronization:
    • When changes are pushed to prod branch, the “Sync Version to Main” workflow automatically runs
    • Creates a PR to sync the production version back to main branch
    • Ensures version consistency across all branches
  3. Production Promotion:
    • “Create PR from latest release to prod” workflow finds the highest release branch
    • Automatically creates PR to promote to production
    • Version information is preserved throughout the process

​
Version Calculation

The automated workflows handle version bumping according to semantic versioning:
  • Major: Increments major version (e.g., 1.2.3 → 2.0.0)
  • Minor: Increments minor version (e.g., 1.2.3 → 1.3.0)
  • Patch: Increments patch version (e.g., 1.2.3 → 1.2.4)

​
Manual Version Updates

Version updates are handled automatically by GitHub Actions. Manual version changes should be avoided to prevent conflicts with the automated system.
Note: All version management is handled through GitHub Actions workflows. The version in apps/webapp/package.json is automatically updated during the release process and synchronized across branches. Internal packages (packages/*) have no version fields and don’t require management.

​
URLs

  • Staging: cona.run
  • Production: cona.app