StarterApp Docs
CI/CD

Overview

Automated validation and deployment pipeline

Continuous integration validates code changes through automated lint, typecheck, test, and build stages. Deployment pipelines handle environment promotion from preview to production with minimal manual intervention.

Pro Tip

The CI/CD pipeline runs all validation jobs in parallel, providing feedback within minutes. Aggressive caching reduces cold build times significantly.

Pipeline Architecture

The framework implements a validation pipeline defined in .github/workflows/ci.yml:

CI workflow structure
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  lint:      # Code formatting and style
  typecheck: # TypeScript validation
  test:      # Unit tests with coverage
  build:     # Production compilation
  e2e:       # End-to-end smoke tests

All jobs except E2E run in parallel.

Job dependency graph
graph TD
    A[Push/PR] --> B[Lint]
    A --> C[Type Check]
    A --> D[Test]
    A --> E[Build]
    E --> F[E2E Tests]
    B --> G[Merge]
    C --> G
    D --> G
    F --> G

E2E tests depend on successful build completion.

The pipeline caches dependencies and build outputs:

  • pnpm store - Node modules across jobs
  • Turbo cache - Build artifacts and outputs
  • Playwright browsers - E2E test dependencies
  • Coverage reports - Historical test data

CI Workflow Stages

Lint Job

Validates code formatting and style with Ultracite (Biome):

Lint job configuration
lint:
  name: Lint
  runs-on: ubuntu-latest

  steps:
    - uses: actions/checkout@v4
    - uses: pnpm/action-setup@v4
    - uses: actions/setup-node@v4
      with:
        node-version-file: '.nvmrc'
        cache: 'pnpm'
    - run: pnpm install --frozen-lockfile
    - run: pnpm lint

Checks:

  • Code formatting consistency
  • Import/export organization
  • Unused variables and imports
  • Code complexity metrics

Type Check Job

Ensures TypeScript strict mode compliance:

Typecheck job configuration
typecheck:
  name: Type Check
  runs-on: ubuntu-latest

  steps:
    - uses: actions/checkout@v4
    - uses: pnpm/action-setup@v4
    - uses: actions/setup-node@v4
      with:
        node-version-file: '.nvmrc'
        cache: 'pnpm'
    - run: pnpm install --frozen-lockfile
    - run: pnpm typecheck

Validates:

  • Strict TypeScript types across workspace
  • Proper type imports and exports
  • Generics and utility types

Test Job

Runs unit tests with Vitest:

Test job configuration
test:
  name: Test
  runs-on: ubuntu-latest

  steps:
    - uses: actions/checkout@v4
    - uses: pnpm/action-setup@v4
    - uses: actions/setup-node@v4
      with:
        node-version-file: '.nvmrc'
        cache: 'pnpm'
    - run: pnpm install --frozen-lockfile
    - run: pnpm test
    - uses: actions/upload-artifact@v4
      if: always()
      with:
        name: coverage-report
        path: coverage/
        retention-days: 30

Coverage includes:

  • Authentication flows
  • Billing integration
  • Security helpers
  • API route handlers

Build Job

Compiles production artifacts with Turbo:

Build job configuration
build:
  name: Build
  runs-on: ubuntu-latest

  steps:
    - uses: actions/checkout@v4
    - uses: pnpm/action-setup@v4
    - uses: actions/setup-node@v4
      with:
        node-version-file: '.nvmrc'
        cache: 'pnpm'
    - run: pnpm install --frozen-lockfile
    - run: pnpm turbo run build --cache-dir=.turbo
      env:
        APP_BASE_URL: http://localhost:3000
        CONVEX_DEPLOYMENT: skip
        NEXT_PUBLIC_CONVEX_URL: https://placeholder.convex.cloud
        SKIP_ENV_VALIDATION: true

CI Build Configuration

SKIP_ENV_VALIDATION=true allows builds without server secrets. Convex codegen is skipped since generated files are committed.

E2E Job

Runs Playwright smoke tests:

E2E job configuration
e2e:
  name: E2E Tests
  runs-on: ubuntu-latest
  needs: [build]

  steps:
    - uses: actions/checkout@v4
    - uses: pnpm/action-setup@v4
    - uses: actions/setup-node@v4
      with:
        node-version-file: '.nvmrc'
        cache: 'pnpm'
    - run: pnpm install --frozen-lockfile
    - run: pnpm exec playwright install --with-deps chromium
    - run: pnpm test:e2e:smoke
      env:
        APP_BASE_URL: http://127.0.0.1:3000
        DASHBOARD_BASE_URL: http://127.0.0.1:3001
        SKIP_ENV_VALIDATION: true
    - uses: actions/upload-artifact@v4
      if: always()
      with:
        name: playwright-report
        path: playwright-report/
        retention-days: 30

Test coverage:

  • Homepage rendering
  • Navigation flows
  • Form submissions
  • Accessibility checks

Quality Standards

Local Validation

Run validation locally before pushing:

Complete validation
# Run all CI checks locally
pnpm validate

# Includes:
# - Linting
# - Type checking
# - Unit tests
# - Production build
Targeted validation
# Format and lint
pnpm lint

# Type check with watch mode
pnpm typecheck:watch

# Run tests in watch mode
pnpm test:watch

# Build specific app
pnpm turbo run build --filter=marketing

Husky enforces quality before commits:

.husky/pre-commit
#!/bin/sh
pnpm lint-staged
package.json
{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": ["ultracite fix"],
    "*.{json,md,mdx}": ["ultracite fix"]
  }
}

Auto-formats files on commit.

Preview Deployments

Every pull request receives unique preview deployments:

Vercel Previews

Automatic preview URLs on every PR with instant rollback capability

Netlify Previews

Deploy previews with unique URLs and branch-specific configuration

Preview capabilities:

  • Isolated testing environments
  • Stakeholder review without merging
  • Visual regression detection
  • Performance impact analysis

Production Deployment

The production deployment process:

PR Approval Required

Branch protection rules enforce:

  • At least 1 approving review
  • All CI checks passing
  • No merge conflicts
  • Up-to-date with base branch

Automated Deployment

Merging to main triggers:

  • Production build with optimizations
  • Environment-specific configuration
  • Health check verification
  • Automatic rollback on failure

Post-Deployment Validation

Verify deployment success:

Health checks
# Health check endpoint
curl https://your-domain.com/api/health

# Authentication endpoint
curl https://your-domain.com/api/auth/session

# Convex connection test
# (Check browser console for WebSocket)

AI-Assisted Pipeline Management

AI assistants understand CI/CD patterns and can configure workflows:

AI Deployment Automation

Use llms/commands/deploy.md for interactive deployment guidance with platform-specific optimizations.

AI commands
# Setup GitHub Actions
Read llms/templates and configure CI workflow

# Add new quality gates
Add bundle size monitoring to CI pipeline

# Debug pipeline failures
Analyze CI logs and fix failing tests

CI/CD Process

Detailed workflow from commit to production deployment

GitHub Integration

Repository automation, branch protection, and secrets management

Release Checklist

Security and configuration review before production deploys

CI/CD Process

Code flow from commit to production deployment

On this page

Pipeline ArchitectureCI Workflow StagesLint JobType Check JobTest JobBuild JobE2E JobQuality StandardsLocal ValidationPreview DeploymentsProduction DeploymentPR Approval RequiredAutomated DeploymentPost-Deployment ValidationAI-Assisted Pipeline ManagementRelated Documentation