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

dev

main

GitHub Actions Workflows

Location:

.github/workflows/

pr-quality-check.yml

deploy-migrations.yml

deploy-staging-migrations.yml

sync-db-types.yml

sentry-release.yml

codeql.yml

dependabot-auto-merge.yml

sync-prod-data-to-staging.yml

PR Quality Check (

pr-quality-check.yml

)

Runs on PRs targeting

main

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

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)

format

validate-wip

validate-migrations

validate-rls-policies

check-version-suffixes

validate-json-keys

validate-db-local

Pre-push Hooks (< 15 seconds default)

oxlint

lint

typecheck

validate-lockfile

validate-db-local

validate-db-types

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

validate-db-local.sh

validate-migrations.sh

validate-json-keys.sh

validate-wip.sh

check-version-suffixes.sh

analyze-rls-policies.sh

Deployment Scripts

deploy-production.sh

deploy-env-vars.sh

apply-staging-migrations.sh

setup-staging-environment.sh

setup-complete-staging.sh

Utility Scripts

git-worktree.sh

clean-env-vars.sh

update-supabase-email-templates.sh

Environment Configuration

GitHub Secrets Required

SUPABASE_PROJECT_ID

SUPABASE_DB_PASSWORD

SUPABASE_ACCESS_TOKEN

STAGING_SUPABASE_PROJECT_ID

STAGING_SUPABASE_DB_PASSWORD

SENTRY_AUTH_TOKEN

SENTRY_ORG

SENTRY_PROJECT

GitHub Variables

ENABLE_DB_TYPE_SYNC

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

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