StarterApp Docs
CI/CD

CI/CD Process

Code flow from commit to production deployment

A six-stage pipeline manages code from local development through production deployment. Each stage validates different aspects of code quality, building confidence through automated checks.

Pro Tip

The framework implements local validation, git push, CI checks, pull request review, merge protection, and production deployment. Each stage provides specific quality gates.

Pipeline Stages

Pipeline flow
graph LR
    A[Local Dev] -->|pnpm validate| B[Git Push]
    B -->|GitHub Actions| C[CI Checks]
    C -->|All Pass| D[PR Review]
    D -->|Approved| E[Merge to Main]
    E -->|Automatic| F[Deploy Preview]
    F -->|Verified| G[Deploy Production]

    style A fill:#1a1a1a
    style B fill:#1a1a1a
    style C fill:#0d9488
    style D fill:#0d9488
    style E fill:#0d9488
    style F fill:#3b82f6
    style G fill:#10b981

Stage 1: Local Development

Local validation catches issues before pushing:

Run Complete Validation

Full validation suite
pnpm validate

This command executes:

  • Linting (Ultracite with auto-fix)
  • Type checking (TypeScript across all packages)
  • Unit tests (Vitest with coverage)
  • Production build (Next.js compilation)

Fast Feedback

Run pnpm validate before committing. Local validation provides immediate feedback.

Fix Issues Individually

When validation fails, run targeted commands:

Auto-fix formatting
pnpm format

Formats code with Ultracite (Biome).

Lint commands
# Check linting rules
pnpm lint

# Auto-fix where possible
pnpm lint:fix

Reports style violations and potential bugs.

Type checking
pnpm typecheck

Identifies type errors across the monorepo.

Test commands
# Run unit tests
pnpm test

# Watch mode during development
pnpm test:watch

# E2E smoke tests
pnpm test:e2e:smoke

Verifies functionality and prevents regressions.

Stage 2: Git Push

Conventional commits create clear history:

Commit with Conventional Format

Conventional commit
git add .
git commit -m "feat(dashboard): add subscription management UI"
git push origin feature/subscriptions

Commit format: <type>(<scope>): <description>

Types:

  • feat - New feature
  • fix - Bug fix
  • docs - Documentation changes
  • refactor - Code restructuring without behavior change
  • test - Test additions or modifications
  • chore - Build process or tooling updates

Semantic Versioning

Conventional commits enable automatic changelog generation and semantic version bumps during releases.

Pre-Commit Hooks

Git hooks automatically run before commits:

package.json
{
  "simple-git-hooks": {
    "pre-commit": "pnpm lint-staged"
  }
}

Lint-staged configuration:

  • Formats staged files with Ultracite
  • Type checks affected files
  • Prevents committing broken code

Stage 3: CI Validation

Parallel job execution in .github/workflows/ci.yml:

Lint job
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

Validates code style consistency across the monorepo.

Typecheck job
typecheck:
  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

Compiles TypeScript across all packages and apps.

Test job
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/

Runs Vitest unit tests with coverage reporting.

Build job
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

Builds all applications without deployment secrets.

Build-Safe Environment

SKIP_ENV_VALIDATION=true allows building without production credentials. Server-only environment variables are optional in CI.

E2E job
e2e:
  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
    - uses: actions/upload-artifact@v4
      if: always()
      with:
        name: playwright-report
        path: playwright-report/

Runs Playwright smoke tests against critical user paths.

CI Optimization Features

Stage 4: Pull Request Review

Pull requests provide comprehensive status visibility:

CI Status Checks

GitHub displays all job results in the PR:

  • Lint (required)
  • Type Check (required)
  • Test (required)
  • Build (required)
  • E2E Tests (required)

All checks must pass before merging.

Merge Blocking

Branch protection rules prevent merging with failing checks. Fix issues before requesting review.

Preview Deployments

Vercel/Netlify create preview URLs automatically:

Preview URL format
https://starterapp-git-feature-branch-username.vercel.app

Reviewers test functionality in deployed environment before approving.

Code Review

Team members review:

  • Logic correctness
  • Security implications
  • Performance considerations
  • API design
  • Test coverage

At least one approval required before merging.

Stage 5: Merge Protection

Branch protection rules safeguard main branch:

Stage 6: Production Deployment

The production pipeline:

Automatic Staging Deploy

After merging to main, platforms automatically deploy to staging:

Staging URL
https://staging.your-domain.com

This environment mirrors production configuration with test credentials.

Staging Verification

Run checks against staging:

Production Promotion

After staging verification, promote to production:

Deploy to production
vercel --prod
Deploy to production
netlify deploy --prod

Console → Promote branch to production

Health Checks

Verify production deployment:

Post-deployment verification
# Homepage responds
curl -I https://your-domain.com
# Expected: HTTP 200

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

# Convex connection
curl https://your-domain.com/api/health
# Expected: { "status": "ok" }

Monitor error rates and response times post-deploy.

Deployment Strategies

Preview deployments create isolated environments for every PR:

  • Unique URL per branch
  • Full production-like environment
  • Automatic cleanup after merge
  • Stakeholder testing without affecting production

Best for: Feature validation and stakeholder review

Canary deployments route small traffic percentage to new version:

vercel.json
{
  "github": {
    "autoAlias": true
  },
  "trailingSlash": false,
  "redirects": [
    {
      "source": "/canary",
      "destination": "https://canary-deployment.vercel.app",
      "percentage": 5
    }
  ]
}

Monitor error rates. Rollback if metrics degrade.

Best for: High-risk changes requiring gradual rollout

Blue-green deployments maintain two identical production environments:

  • Blue: Current production
  • Green: New version

Deploy to green, verify, then switch traffic. Instant rollback by switching back.

Best for: Zero-downtime deployments with instant rollback capability

Feature flags deploy disabled code for controlled activation:

apps/dashboard/lib/features.ts
export function isFeatureEnabled(feature: string): boolean {
  const flags = {
    newBillingUI: process.env.ENABLE_NEW_BILLING === "true",
    aiAssistant: process.env.ENABLE_AI_ASSISTANT === "true",
  };
  return flags[feature] ?? false;
}

Enable features gradually per user cohort.

Best for: Progressive rollout with fine-grained control

Git Workflows

AI-Assisted Pipeline Development

AI assistants understand pipeline patterns:

AI workflow commands
Read .github/workflows/ci.yml and suggest optimizations

The AI can:

  • Add new jobs for package-specific validations
  • Optimize slow jobs with better caching
  • Create deployment workflows
  • Configure scheduled maintenance tasks
  • Generate status badges for README

Overview

Automated validation and deployment pipeline

GitHub Integration

Repository automation with branch protection and secrets management

On this page

Pipeline StagesStage 1: Local DevelopmentRun Complete ValidationFix Issues IndividuallyStage 2: Git PushCommit with Conventional FormatPre-Commit HooksStage 3: CI ValidationCI Optimization FeaturesStage 4: Pull Request ReviewCI Status ChecksPreview DeploymentsCode ReviewStage 5: Merge ProtectionStage 6: Production DeploymentAutomatic Staging DeployStaging VerificationProduction PromotionHealth ChecksDeployment StrategiesGit WorkflowsAI-Assisted Pipeline Development