CI/CD Pipeline

CI/CD Pipeline Documentation

Generated: 2026-01-04

Overview

NexisChat uses GitHub Actions for continuous integration and deployment. The pipeline is optimized for monorepo workflows using Turborepo change detection.

Workflow Files

Workflow	Trigger	Purpose
ci.yml	Push, PR	Main CI pipeline
change-detection.yml	Called	Detect changed packages
storybook-tests.yml	Push (main)	Visual regression tests
knip.yml	PR	Unused code detection
todo-to-issue.yml	Push (main)	Convert TODOs to issues

Main CI Pipeline (ci.yml)

Trigger Conditions

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

Job Structure

┌─────────────────┐
│ change-detection│  Determine affected packages
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    typecheck    │  TypeScript validation
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌───────┐ ┌───────┐
│ lint  │ │format │  Code quality
└───┬───┘ └───┬───┘
    │         │
    └────┬────┘
         ▼
┌─────────────────┐
│     build       │  Production builds
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│      test       │  Unit tests + coverage
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    coverage     │  Upload to Codecov
└─────────────────┘

Change Detection

The pipeline uses Turborepo’s --filter to only process changed packages:

jobs:
  change-detection:
    runs-on: ubuntu-latest
    outputs:
      client: ${{ steps.filter.outputs.client }}
      server: ${{ steps.filter.outputs.server }}
      ui: ${{ steps.filter.outputs.ui }}
    steps:
      - uses: actions/checkout@v4
      - uses: dorny/paths-filter@v2
        id: filter
        with:
          filters: |
            client:
              - 'apps/client/**'
              - 'packages/ui/**'
            server:
              - 'apps/server/**'
            ui:
              - 'packages/ui/**'

Caching Strategy

- name: Setup pnpm
  uses: pnpm/action-setup@v4

- name: Setup Node
  uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'pnpm'

- name: Turborepo Cache
  uses: actions/cache@v4
  with:
    path: .turbo
    key: turbo-${{ runner.os }}-${{ hashFiles('**/pnpm-lock.yaml') }}
    restore-keys: |
      turbo-${{ runner.os }}-

Test Coverage

- name: Run Tests
  run: pnpm test:coverage

- name: Upload Coverage
  uses: codecov/codecov-action@v4
  with:
    files: ./apps/server/coverage/lcov.info,./packages/ui/coverage/lcov.info
    fail_ci_if_error: false

Storybook Tests (storybook-tests.yml)

Visual regression testing with Chromatic:

on:
  push:
    branches: [main]
    paths:
      - 'packages/ui/**'

jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Required for Chromatic

      - name: Install dependencies
        run: pnpm install

      - name: Build Storybook
        run: pnpm --filter ui build:storybook

      - name: Chromatic
        uses: chromaui/action@v1
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          workingDir: packages/ui

Knip Analysis (knip.yml)

Detect unused exports, dependencies, and files:

on:
  pull_request:
    branches: [main]

jobs:
  knip:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pnpm install
      - run: pnpm knip

Self-Hosted Runner

The CI uses a self-hosted runner for faster builds:

jobs:
  build:
    runs-on: self-hosted
    # Fallback to ubuntu-latest if self-hosted unavailable

Runner Setup

1. Install GitHub Actions runner on build machine
2. Configure with repository access
3. Install required tools: Node.js, pnpm, Docker
4. Add labels: self-hosted, linux, x64

Environment Variables

CI Secrets

Secret	Used By	Purpose
DATABASE_URL	server, whatsapp-web-server	Test database
WORKOS_CLIENT_ID	server	Auth testing
WORKOS_API_KEY	server	Auth testing
CREEM_API_KEY	server	Payment testing
SENTRY_DSN	client, subscription	Error tracking
CODECOV_TOKEN	CI	Coverage uploads
CHROMATIC_PROJECT_TOKEN	ui	Visual tests

Environment Setup

env:
  CI: true
  DATABASE_URL: ${{ secrets.DATABASE_URL }}
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: ${{ secrets.TURBO_TEAM }}

Deployment

Vercel (Client, Subscription, Docs, Landing)

Automatic deployments via Vercel GitHub integration:

1. Push to main → Production deploy
2. Push to PR → Preview deploy

Configuration in vercel.json per app.

Railway (Server, WhatsApp Web Server)

Deploy via Railway GitHub integration:

1. Connect repository
2. Configure build command: pnpm --filter server build
3. Configure start command: pnpm --filter server start
4. Set environment variables

Branch Protection

Main Branch Rules

• Require pull request before merge
• Require status checks:
  • typecheck
  • lint
  • build
  • test
• Require up-to-date branches
• Require linear history (squash merge)

Local CI Simulation

Test CI pipeline locally with act:

# Install act
brew install act

# Run CI workflow
act push

# Run specific job
act -j build

# With secrets
act --secret-file .secrets

Troubleshooting

Cache Issues

# Clear Turborepo cache
rm -rf .turbo

# Clear pnpm cache
pnpm store prune

Flaky Tests

1. Check for race conditions
2. Ensure test isolation
3. Use deterministic mocks
4. Add retry configuration:

- name: Run Tests
  run: pnpm test
  env:
    VITEST_MAX_THREADS: 1 # Reduce parallelism

Build Failures

1. Check Node.js version matches local
2. Verify all dependencies in pnpm-lock.yaml
3. Check for missing environment variables
4. Review Turborepo pipeline dependencies

Monitoring

GitHub Actions Insights

• View workflow runs: Actions tab
• Check run times: Actions → Workflow → Run
• Download artifacts: Actions → Run → Artifacts

Codecov Dashboard

• Coverage trends
• PR coverage diff
• File-level coverage

Chromatic Dashboard

• Visual diff review
• Component snapshots
• Build history