cicd-pipeline

CI/CD pipeline guide covering GitHub Actions, Lefthook hooks, Dependabot, and deployment scripts. Use when asking about workflows, automation, or deployment.

SKILL.md

GitHub

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/

Workflow Trigger Purpose
pr-quality-check.yml PR to main/develop Lint, typecheck, test, build
deploy-migrations.yml Push to main (*.sql) Deploy migrations to production
deploy-staging-migrations.yml Push to dev (*.sql) Deploy migrations to staging
sync-db-types.yml Push to dev (*.sql) Auto-generate TypeScript types
sentry-release.yml Deployment success Create Sentry release + sourcemaps
codeql.yml Push/PR + weekly schedule Security vulnerability scanning
dependabot-auto-merge.yml Dependabot PRs Auto-merge patch/minor updates
sync-prod-data-to-staging.yml Manual Sync production data to staging

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)

Hook Files Purpose
format *.ts,tsx,json,md... Prettier auto-fix
validate-wip WIP_*.md WIP document validation
validate-migrations *.sql Migration syntax check
validate-rls-policies *.sql RLS security validation
check-version-suffixes *.ts,tsx Block -v2, -new naming
validate-json-keys *.json Detect duplicate keys
validate-db-local *.ts,tsx,sql DB contract validation

Pre-push Hooks (< 15 seconds default)

Hook Purpose
oxlint Fast lint sanity check
lint Full ESLint (THOROUGH=1 only)
typecheck Full TypeScript (THOROUGH=1 only)
validate-lockfile pnpm-lock.yaml sync check
validate-db-local DB validation
validate-db-types Info about auto-sync

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

Script Purpose
validate-db-local.sh Local DB contract validation
validate-migrations.sh Migration file validation
validate-json-keys.sh Detect duplicate JSON keys
validate-wip.sh WIP document validation
check-version-suffixes.sh Block forbidden naming patterns
analyze-rls-policies.sh RLS security analysis

Deployment Scripts

Script Purpose
deploy-production.sh Manual production deployment
deploy-env-vars.sh Deploy env vars to Vercel
apply-staging-migrations.sh Apply migrations to staging
setup-staging-environment.sh Full staging setup
setup-complete-staging.sh Complete staging rebuild

Utility Scripts

Script Purpose
git-worktree.sh Git worktree management
clean-env-vars.sh Clean trailing newlines from env
update-supabase-email-templates.sh Deploy email templates

Environment Configuration

GitHub Secrets Required

Secret Description
SUPABASE_PROJECT_ID Production project ID
SUPABASE_DB_PASSWORD Production DB password
SUPABASE_ACCESS_TOKEN Supabase management token
STAGING_SUPABASE_PROJECT_ID Staging project ID
STAGING_SUPABASE_DB_PASSWORD Staging DB password
SENTRY_AUTH_TOKEN Sentry release token
SENTRY_ORG Sentry organization
SENTRY_PROJECT Sentry project name

GitHub Variables

Variable Description
ENABLE_DB_TYPE_SYNC Enable/disable type sync (default: true)

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