Skip to content

CI/CD Guide

Continuous Integration and Deployment setup for the Microlearning Platform

Overview

This project uses a 3-tier PR-based validation pipeline optimized for:

  • Speed: Fast feedback in 1-2 minutes, full validation in 8-10 minutes
  • Cost: $0/month (GitHub Actions free tier)
  • Quality: 22 E2E test suites with coverage reporting
  • Agentic Development: Compatible with Claude Code workflows

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Local Development                         │
│  • Pre-commit hooks (lint, format, types)                   │
│  • Pre-push hooks (tests on main/develop)                   │
└────────────────────┬────────────────────────────────────────┘
                     │ git push
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                   GitHub PR Opened/Updated                   │
└────────────────────┬────────────────────────────────────────┘
                     │
        ┌────────────┴────────────┐
        │                         │
┌───────▼──────────┐   ┌─────────▼──────────┐
│ Tier 1: Fast     │   │ Tier 2: Integration│
│ • Lint (30s)     │   │ • Start Supabase   │
│ • Format (30s)   │   │ • Run 22 E2E tests │
│ • Type (1m)      │   │ • Coverage report  │
│ Total: ~2min     │   │ Total: ~10min      │
└─────┬────────────┘   └─────────┬──────────┘
      │                          │
      └──────────┬───────────────┘
                 │ All Pass?
                 ▼
      ┌──────────────────────┐
      │ Tier 3: Deploy       │
      │ Preview (Optional)   │
      │ • Edge Functions     │
      │ • Smoke tests        │
      │ Total: ~3min         │
      └──────────┬───────────┘
                 │
                 ▼
          ✅ Ready to Merge
                 │
                 ▼ Merge to main
      ┌──────────────────────┐
      │ Production Deploy    │
      │ • Deploy changed     │
      │ • Health checks      │
      │ • Migrations (auto)  │
      └──────────────────────┘

Workflows

1. PR Validation (.github/workflows/pr-checks.yml)

Triggers:

  • Pull request opened
  • New commit pushed to PR
  • PR marked ready for review

Jobs:

Job Duration Description
fast-checks ~2 min Lint, format, type check
integration-tests ~10 min Full E2E test suite + coverage
deploy-preview ~3 min Deploy to preview environment (non-draft PRs only)

Status Checks:

  • ✅ All jobs must pass before merge allowed
  • 📊 Coverage report uploaded to Codecov
  • 💬 PR comments with results
  • 📁 Test results uploaded as artifacts

Optimization:

  • Concurrent cancellation: New commits cancel old runs
  • Dependency caching: Deno deps cached between runs (~60% faster)
  • Parallel execution: Fast checks run independently

2. Production Deployment (.github/workflows/deploy-production.yml)

Triggers:

  • Push to main branch
  • Manual workflow dispatch

Jobs:

Step Description
Deploy Deploy only changed Edge Functions
Health Check Verify all functions are responding
Migrations Auto-apply database migrations if detected
Notification Comment on commit with results

Safety:

  • Sequential deployment (no concurrent runs)
  • Changed functions only (faster, safer)
  • Health checks before marking success
  • Automatic rollback on failure (Supabase native)

Local Development Setup

1. Install Git Hooks (First Time)

# Make setup script executable
chmod +x tools/scripts/setup-git-hooks.sh

# Install hooks
./tools/scripts/setup-git-hooks.sh

What it does:

  • Pre-commit: Runs lint, format, type checks
  • Pre-push: Runs tests before pushing to main/develop

2. Local Validation Commands

# Fast checks (1-2 min)
deno task lint            # Lint code
deno task fmt             # Auto-format
deno task fmt --check     # Check format without fixing
deno task check           # Type check

# Run all fast checks
deno task lint && deno task fmt --check && deno task check

# Unit tests (if any in src/)
deno task test

# Integration tests (8-10 min)
deno task local:setup        # Start Supabase + seed
deno task test:e2e:all         # Run all E2E tests
deno task test:e2e:coverage # With coverage report

# Specific test suites
deno task test:e2e:graph   # Graph API only
deno task test:e2e:user    # User API only
deno task test:e2e:protection # Auth/authz only

3. Development Workflow

# 1. Create feature branch
git checkout -b feature/my-feature

# 2. Make changes and commit (pre-commit hook runs automatically)
git add .
git commit -m "feat: Add new feature"
# → Runs lint, format, type checks

# 3. Push to GitHub (pre-push hook runs tests)
git push origin feature/my-feature
# → Runs tests before push

# 4. Open PR
# → GitHub Actions runs full validation

# 5. Iterate based on CI feedback
# → Fix issues, push again (cancels old CI runs)

# 6. Merge when green ✅
# → Auto-deploys to production

GitHub Secrets Setup

Required secrets in GitHub repository settings:

Production Deployment

Secret Description How to Get
SUPABASE_ACCESS_TOKEN Supabase API token supabase.com/dashboard/account/tokens
SUPABASE_PROJECT_ID Production project ID From Supabase project URL

Optional (for preview environments)

Secret Description
SUPABASE_PREVIEW_PROJECT_ID Separate Supabase project for PR previews
CODECOV_TOKEN Codecov API token for coverage uploads

Test Environment (Optional - uses default keys)

Secret Description
SUPABASE_ANON_KEY Override default anon key for tests
SUPABASE_SERVICE_ROLE_KEY Override default service role key

Note: Test environment uses Supabase default demo keys by default, so these secrets are optional.

Cost Analysis

GitHub Actions Free Tier

Repository Type Free Minutes/Month Your Usage Cost
Public Unlimited N/A $0
Private 2,000 min/month ~780 min/month $0

Breakdown (20 PRs/month):

  • PR fast checks: 2 min × 60 runs = 120 min
  • PR integration tests: 10 min × 60 runs = 600 min
  • PR preview deploys: 3 min × 20 runs = 60 min
  • Production deploys: 3 min × 20 merges = 60 min
  • Total: ~840 min/month ✅ Free

Optimization Tips

  1. Concurrent cancellation: Already enabled, prevents wasted minutes
  2. Dependency caching: Already enabled, saves ~60% time
  3. Fast checks first: Fail early without running expensive tests
  4. Changed functions only: Deploy only what changed
  5. Conditional preview: Only deploy preview for ready PRs

Troubleshooting

CI fails but works locally

Likely causes:

  1. Cached dependencies: Clear cache in GitHub Actions settings
  2. Environment differences: Check Deno versions match
  3. Missing secrets: Verify required secrets are set

Solution:

# Match CI environment locally
deno task local:setup
deno task test:e2e:ci  # Same command as CI

Tests timeout in CI

Likely causes:

  1. Supabase not ready yet
  2. Edge functions not started
  3. Network timeouts

Solution:

  • Increase timeout: timeout-minutes: 30 in workflow
  • Add health check wait: timeout 60 bash -c 'until curl ...'
  • Check test timeout: TEST_TIMEOUT_MS=60000 env var

Deployment fails

Likely causes:

  1. Invalid access token
  2. Wrong project ID
  3. Function code errors

Solution:

# Test deployment locally
export SUPABASE_ACCESS_TOKEN=your-token
export SUPABASE_PROJECT_ID=your-project-id
deno task deploy:check

Pre-commit hooks block commit

Temporary bypass:

git commit --no-verify -m "WIP: Bypassing hooks"

Permanent disable:

rm .git/hooks/pre-commit
rm .git/hooks/pre-push

Re-enable:

./tools/scripts/setup-git-hooks.sh

Best Practices

For Solo Founders

  1. Work in small PRs: Easier to review, faster CI runs
  2. Use draft PRs: Skip preview deploy until ready
  3. Local validation first: Use pre-commit hooks
  4. Trust the pipeline: Don't merge yellow PRs
  5. Check coverage trends: Use Codecov to track coverage

For Agentic Development (Claude Code)

  1. Let CI validate agent changes: Don't merge without green checks
  2. Use PR comments for feedback: CI posts results directly
  3. Iterate with agent: Agent can fix lint/format failures automatically
  4. Review test failures carefully: Agents can introduce subtle bugs
  5. Keep test fixtures updated: Update tests/e2e/fixtures/ when schema changes

For Team Growth

  1. Branch protection rules: Require status checks before merge
  2. Required reviewers: At least 1 approval for main
  3. Linear history: Use squash or rebase merge
  4. Semantic versioning: Tag releases for production deploys
  5. Changelog: Auto-generate from commit messages

Monitoring

GitHub Actions Dashboard

  • View all runs: https://github.com/<user>/<repo>/actions
  • PR checks: Visible in PR "Checks" tab
  • Failed runs: Email notifications + PR comments

Codecov Dashboard

  • Coverage trends: https://codecov.io/gh/<user>/<repo>
  • PR coverage diff: Automatic PR comments
  • Uncovered lines: Highlighted in PR diff

Supabase Logs

# View function logs
deno task supabase:logs graph

# View all logs
supabase logs --project-id your-project-id

Migration from Existing Setup

Your existing workflow (.github/workflows/integration-tests.yml) is already solid. Here's the migration path:

  1. Keep existing workflow as-is
  2. Add new pr-checks.yml for enhanced PR validation
  3. Test both in parallel for 1-2 weeks
  4. Archive old workflow once confident

Option 2: Replace

  1. Backup existing workflow: mv integration-tests.yml integration-tests.yml.backup
  2. Use new pr-checks.yml as primary
  3. Monitor for issues
  4. Delete backup after 1 month

Recommendation: Option 1 - Keep both, disable old one after validation period.

Advanced Features (Future)

  • Parallel test execution: Split E2E tests across multiple runners
  • Matrix testing: Test against multiple Deno/Supabase versions
  • Nightly builds: Daily full test runs on develop
  • Performance benchmarks: Track API response times over time
  • Security scanning: Dependency vulnerability checks (Dependabot)
  • Preview environments: Per-PR Supabase instances (requires paid plan)

References

Support

Issues with CI/CD:

  1. Check this guide
  2. Review workflow run logs
  3. Test locally with same commands
  4. Open GitHub issue with workflow run URL

Cost concerns:

  • Monitor Actions usage: Settings → Billing → Actions
  • Set spending limits: Settings → Billing → Spending limits
  • Optimize workflows: Profile run times, cache aggressively