CI/CD Pipeline Skill

Comprehensive guide to Ballee's CI/CD infrastructure including GitHub Actions, git hooks, scripts, and deployment processes.

Overview

Ballee uses a multi-layered CI/CD approach:

1. Local Git Hooks (Lefthook) - Fast pre-commit/pre-push validation
2. GitHub Actions - PR quality checks, migrations, deployments
3. Dependabot - Automated security updates with auto-merge
4. Vercel - Production/staging deployments (automatic)

Branch Strategy

main     → Production (protected, requires PR + Quality Gate)
dev      → Development/Staging (Dependabot target)
feat/*   → Feature branches (via git worktrees)
fix/*    → Bug fix branches

Workflow: feat/branch → PR to dev → PR to main → Production

GitHub Actions Workflows

Location: .github/workflows/

PR Quality Check (pr-quality-check.yml)

Runs on PRs targeting main or develop:

Jobs:
  1. detect-changes    # Smart change detection
  2. oxlint           # Fast lint (~1 min) - fail-fast
  3. lint             # Full ESLint
  4. typecheck        # TypeScript validation
  5. test             # Unit + integration tests
  6. build            # Production build verification
  7. quality-gate     # Final approval status

Key Features:

• Cancels in-progress runs on new commits
• Skips irrelevant jobs based on changed files
• Parallel execution for speed

Migration Deployment (deploy-migrations.yml)

Triggers on push to main with SQL changes:

Steps:
  1. Validate migration files (no duplicates)
  2. Check pending migrations
  3. Apply via psql (supports complex SQL)
  4. Generate TypeScript types
  5. Create PR with type updates

Connection: Uses Supabase pooler (IPv4) for GitHub Actions compatibility

Database Type Sync (sync-db-types.yml)

Auto-generates TypeScript types after migration changes:

Trigger: Push to dev with *.sql changes
Output:
  - packages/supabase/src/database.types.ts
  - apps/web/lib/database.types.ts

Local Git Hooks (Lefthook)

Configuration: lefthook.yml

Pre-commit Hooks (< 2 seconds target)

Pre-push Hooks (< 15 seconds default)

Usage

# Normal push (fast, ~15s)
git push

# Thorough push (full checks, ~5min)
THOROUGH=1 git push

# Skip hooks (emergency only)
git push --no-verify

# Skip specific hook
LEFTHOOK_EXCLUDE=check-version-suffixes git commit -m "..."

Dependabot Configuration

Location: .github/dependabot.yml

Target Branch: dev
Schedule: Weekly (Monday 06:00 Europe/Zurich)

Ecosystems:
  - npm (security updates only)
  - github-actions (all updates)

Auto-merge Workflow

# .github/workflows/dependabot-auto-merge.yml
Behavior:
  - Patch/Minor: Auto-approve + auto-merge
  - Major: Comment notification, manual review required

Reusable Actions

Location: .github/actions/

setup-node-pnpm

Composite action for consistent Node.js setup:

uses: ./.github/actions/setup-node-pnpm
with:
  node-version: '20'        # Default
  install-dependencies: 'true'
  cache-turbo: 'false'
  cache-nextjs: 'false'

Features:

• pnpm v10.14.0 setup
• Node.js with pnpm cache
• Optional Turbo/Next.js caching
• Frozen lockfile install

Scripts

Location: scripts/

CI/CD Related Scripts

Deployment Scripts

Utility Scripts

Environment Configuration

GitHub Secrets Required

GitHub Variables

Vercel Deployment

Handled automatically by Vercel GitHub integration:

Push to dev  → Staging deployment (preview)
Push to main → Production deployment

Environment Variables: Managed via Vercel dashboard or vercel env CLI

Common Commands

Manual Workflow Triggers

# Deploy migrations to production
gh workflow run deploy-migrations.yml --ref main

# Deploy migrations to staging
gh workflow run deploy-staging-migrations.yml --ref dev

# Force regenerate DB types
gh workflow run sync-db-types.yml --ref dev -f force=true

# Create Sentry release
gh workflow run sentry-release.yml -f environment=production

# Sync prod data to staging
gh workflow run sync-prod-data-to-staging.yml

View Workflow Status

# List recent runs
gh run list

# View specific run
gh run view <run-id>

# Watch run in progress
gh run watch

Troubleshooting

Migration Deployment Fails

IPv6 Connection Error:

• Workflows use IPv4 pooler (aws-1-eu-central-1.pooler.supabase.com)
• Already configured, but check if Supabase changed endpoints

Prepared Statement Error:

• Workflows use psql directly, not supabase db push
• Complex SQL with multiple statements is supported

SASL Authentication Failed:

• Check SUPABASE_DB_PASSWORD secret is correct
• Verify using port 5432 (session mode) not 6543 (transaction mode)

Pre-push Hook Slow

# Use fast mode (default)
git push

# Only use thorough mode when needed
THOROUGH=1 git push

Lefthook Not Running

# Reinstall hooks
lefthook install

# Check installation
lefthook run pre-commit

Dependabot Not Auto-merging

1. Verify auto-merge is enabled: gh repo view --json autoMergeAllowed
2. Check branch protection rules allow auto-merge
3. Ensure CI passes before merge

Security Considerations

1. CodeQL runs weekly + on PRs for vulnerability scanning
2. Dependabot monitors security advisories
3. RLS validation in pre-commit hooks
4. No secrets in logs - use GitHub Secrets
5. Protected branches require PR reviews

Related Documentation

• .github/WORKFLOWS.md - Detailed workflow architecture
• .github/REPOSITORY_SAFEGUARDS.md - Branch protection setup
• CLAUDE.md - Overall project guidelines