Skip to content

Deployment

This project utilizes GitHub Actions for automated deployments to Staging and Production environments. The workflows are configured to deploy different components of the application: App (Vercel), Supabase Migrations, aiHub (AWS Fargate), and the API Gateway Authorizer Lambda (AWS Lambda).

Environments

  • Staging: Deployed from the staging branch. Used for testing and QA before promoting to production.
  • Production: Deployed from the main branch. This is the live environment.

Workflow Triggers

All deployment workflows can be triggered in two ways:

  1. Automatic:
  2. Pushing changes to the staging branch will trigger the corresponding Staging deployment workflows if relevant paths are modified.
  3. Pushing changes to the main branch will trigger the corresponding Production deployment workflows if relevant paths are modified.
  4. Manual:
  5. All deployment workflows can be manually triggered from the GitHub Actions tab in the repository. This is useful for re-deploying or for out-of-band deployments. This was enabled by adding workflow_dispatch: to each workflow file.

Workflow Files

The deployment workflows are located in the .github/workflows/ directory:

  • App (Vercel):
  • deploy-app-staging.yml
  • deploy-app-production.yml
  • Supabase Migrations:
  • deploy-supabase-migrations-staging.yml
  • deploy-supabase-migrations-production.yml
  • aiHub (AWS Fargate):
  • deploy-aihub-fargate-staging.yml
  • deploy-aihub-fargate-production.yml
  • API Gateway Authorizer Lambda (AWS Lambda):
  • deploy-authorizer-lambda-staging.yml
  • deploy-authorizer-lambda-production.yml
  • aiHub SQS Processor Lambda (AWS Lambda):
  • deploy-aihub-sqs-processor-lambda-staging.yml
  • deploy-aihub-sqs-processor-lambda-production.yml
  • Storybook (Vercel):
  • deploy-storybook.yml

Feature Promotion Flow

Features move from staging to production using the dual-PR workflow:

  1. Developer merges PR #1 to staging → staging deploys, UAT begins
  2. UAT passes → developer merges PR #2 (same branch) to main → production deploys
  3. After main merge, post-main-merge.yml auto-syncs main into staging and deletes the feature branch

This allows selective production promotion — each feature ships independently.

Hotfixes

For urgent production fixes, developers PR directly to main (skip staging). The post-main-merge.yml workflow auto-syncs the fix into staging.

Staging Hygiene

The reset-staging.yml workflow (manual trigger) resets staging to match main and re-merges any features still in UAT. Run periodically to clean up shipped/abandoned features.

Supporting Workflows

  • post-main-merge.yml — Auto-syncs main into staging after each main merge, deletes feature branches
  • reset-staging.yml — Smart staging reset with auto-re-merge of in-progress features

See docs/development/GIT_WORKFLOW.md for the full developer workflow guide.

Configuration

For the deployment workflows to run successfully, necessary secrets and variables must be configured in your GitHub repository settings:

  • Repository Secrets: Go to Settings > Secrets and variables > Actions.
  • Configure secrets like VERCEL_TOKEN, SUPABASE_ACCESS_TOKEN, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, etc.
  • Environment Secrets & Variables: Some workflows are tied to GitHub Environments (e.g., "Production", "Staging"). Secrets and variables specific to these environments should be configured there.
  • Go to Settings > Environments. Select an environment (or create one if it doesn't exist, matching the environment: name in the workflow files).
  • Add environment-specific secrets (e.g., STAGING_SUPABASE_DB_PASSWORD) and variables (e.g., STAGING_VERCEL_PROJECT_ID).

Refer to the original structure of each workflow YAML file or the respective service deployment guides (Vercel, Supabase, AWS) for details on the specific secrets and variables required for each.

Storybook Deployment

The Storybook deployment provides a separate documentation site for your UI components, deployed to its own Vercel project.

Setup Instructions

1. Create a New Vercel Project for Storybook

  1. Go to Vercel Dashboard
  2. Click "Add New..." → "Project"
  3. Import your repository (same repo as your main project)
  4. Configure the project:
  5. Project Name: delta-storybook (or your preferred name)
  6. Framework Preset: Other
  7. Root Directory: packages/app
  8. Build Command: yarn build-storybook
  9. Output Directory: storybook-static
  10. Install Command: yarn install

2. Configure GitHub Secrets

Add the following secrets to your GitHub repository:

  1. Go to your GitHub repository
  2. Navigate to Settings → Secrets and variables → Actions
  3. Add the following repository secrets:
  4. VERCEL_STORYBOOK_PROJECT_ID: Your Storybook project ID
    • Found in your Vercel project settings for the Storybook project

3. How to Find Vercel Project ID

  1. Go to your Storybook project in Vercel
  2. Go to "Settings"
  3. The Project ID is shown in the "General" tab

4. Deployment Process

The GitHub Action will automatically:

  • On Pull Requests: Deploy a preview version of Storybook
  • On Main Branch: Deploy to production

The workflow triggers when changes are made to:

  • packages/app/src/components/**
  • packages/app/.storybook/**
  • packages/app/src/styles/**

Local Development

To run Storybook locally:

cd packages/app
yarn storybook

This will start Storybook on http://localhost:6006

To build Storybook locally:

cd packages/app
yarn build-storybook

Adding New Stories

  1. Create a .stories.tsx file next to your component
  2. Follow the pattern in src/components/ui/Button.stories.tsx
  3. The story will automatically be picked up by Storybook

Benefits of This Setup

  1. Consistency: Uses the same GitHub Actions approach as your other deployments
  2. Automatic Deployments: Deploys on every relevant change
  3. Preview Deployments: Get preview URLs for pull requests
  4. Separate Project: Keeps Storybook deployment separate from your main app
  5. Optimized Builds: Only rebuilds when component-related files change

Deployment Metrics & Monitoring

All deployment workflows automatically collect and send metrics to Prometheus (Grafana Cloud) for monitoring and observability. This provides valuable insights into your deployment pipeline performance and health.

What Metrics Are Collected

During each deployment, the following metrics are automatically captured and sent to Prometheus:

Build & Deployment Metrics

  • Build Success Rate: Percentage of successful vs failed deployments
  • Deployment Frequency: How often deployments occur to each environment
  • Build Duration: Time taken for builds and deployments to complete
  • Workflow Status: Success/failure status of each deployment job

Test Coverage Metrics

  • Overall Coverage: Combined test coverage percentage across all packages
  • Coverage by Type: Statement, branch, function, and line coverage metrics
  • Test Results: Number of tests run, passed, and failed

Environment Separation

All metrics are automatically tagged with:

  • Service: app or aihub
  • Environment: staging or production (auto-detected from branch)
  • Workflow Details: Workflow name, job name, run ID, commit SHA, and branch

How It Works

  1. Automatic Collection: After each deployment completes (success or failure), a collect-metrics job runs
  2. Non-Intrusive: Metrics collection failures won't break your deployments
  3. Rich Context: Each metric includes comprehensive labels for filtering and alerting
  4. Real-time: Metrics appear in Grafana dashboards immediately after deployment

Configuration Required

To enable metrics collection, configure these GitHub repository settings:

Variables (Settings > Secrets and variables > Actions > Variables):

  • PROMETHEUS_URL: Your Prometheus remote write endpoint
  • PROMETHEUS_USER: Your Prometheus username

Secrets (Settings > Secrets and variables > Actions > Secrets):

  • PROMETHEUS_API_KEY: Your Prometheus API key