CI/CD Workflow

This document explains the complete Continuous Integration and Continuous Deployment (CI/CD) workflow for the Aitana frontend project.

Overview

The project uses a three-environment deployment strategy with automated testing and manual approval gates:

dev → test → prod

Each environment corresponds to a Git branch and has its own deployment pipeline.

Environment Details

Environment Branch URL Purpose
Development dev Internal testing Development and feature integration
Test/Staging test https://ai2.aitana.chat Pre-production testing
Production prod https://ai.aitana.chat Live production environment

Workflow Steps

1. Development Phase

Developer workflow:

  • Work on feature branches based on dev
  • OR commit directly to dev branch for small changes
  • All changes must pass local quality checks

Required local checks:

# Quick quality check (recommended before committing)
npm run quality:check:fast    # lint + typecheck

# Full quality check (before pushing)
npm run quality:check         # lint + typecheck + test + build

# Docker build simulation (exact CI match)
npm run docker:check

2. Test Environment Deployment

Trigger: Pull Request to test branch

Automated process:

  1. Frontend CI Pipeline (cloudbuild.yaml):
    • Firebase rules and indexes deployment
    • Docker image build with Firebase config
    • Template seeding (non-critical)
    • Frontend test coverage generation
    • Badge upload to GCS
    • Multi-container Cloud Run deployment
  2. Backend CI Pipeline (backend/cloudbuild.yaml):
    • Docker image build
    • Parallel test execution:
      • API tests (core endpoints, authentication)
      • Tool tests (AI search, document search, permissions)
      • Integration tests (external services, file processing)
      • Model tests (AI/LLM functionality)
      • Utility tests (utils, monitoring, validation)
    • Coverage report merging
    • Coverage badge generation
    • Cloud Run deployment

Auto-merge policy:

  • If all tests pass, changes can be auto-merged to test
  • Deployed automatically to https://ai2.aitana.chat

3. Manual Testing Phase

Environment: https://ai2.aitana.chat

Process:

  • Manual testing of new features
  • User acceptance testing
  • Performance validation
  • Cross-browser testing

4. Production Deployment

Trigger: Manual approval after successful testing

Requirements:

  • All automated tests must pass
  • Manual testing completed successfully
  • Manual review and approval required

Process:

  • Same CI/CD pipeline as test environment
  • Deployment to production Cloud Run instance
  • Available at https://ai.aitana.chat

5. Documentation Updates

Special workflow:

  • Merge from dev to docs branch
  • Triggers website documentation update
  • GitHub Pages deployment

Quality Gates

Automated Checks

  • ESLint (frontend code quality)
  • TypeScript compilation (type safety)
  • Vitest unit tests (frontend)
  • Pytest test suites (backend)
  • Docker build verification
  • Coverage requirements

Manual Checks

  • Feature functionality verification
  • User experience validation
  • Performance testing
  • Security review

Coverage Requirements

The project maintains high test coverage standards:

Component Coverage Target Badge
Frontend Dev 70%+ Dev Coverage
Frontend Test 70%+ Test Coverage
Frontend Prod 70%+ Prod Coverage
Backend Dev 70%+ Dev Coverage
Backend Test 70%+ Test Coverage
Backend Prod 70%+ Prod Coverage

Pipeline Architecture

Frontend Pipeline

  • Build Environment: Docker with Node.js 18
  • Test Framework: Vitest + React Testing Library
  • Deployment: Google Cloud Run (multi-container)
  • Storage: Firebase, Google Cloud Storage
  • Monitoring: Coverage badges, build logs

Backend Pipeline

  • Build Environment: Python 3.12 with uv
  • Test Framework: Pytest with parallel execution
  • Deployment: Google Cloud Run
  • Dependencies: Vertex AI, Anthropic, Langfuse
  • Configuration: GCS-mounted config volumes

Rollback Strategy

Automated rollback triggers:

  • Critical test failures
  • Health check failures
  • Performance degradation

Manual rollback process:

  1. Identify the last known good deployment
  2. Revert to previous Git commit
  3. Re-trigger deployment pipeline
  4. Verify rollback success

Monitoring and Alerts

Health Monitoring:

  • Cloud Run health checks
  • Application performance monitoring
  • Error rate tracking
  • Coverage trend monitoring

Alert Channels:

  • GitHub Actions notifications
  • Cloud Build status updates
  • GCS storage alerts