Skip to main content

Source: ocean/docs/build-security.md | ✏️ Edit on GitHub

Build Security Best Practices

Overview​

This document outlines our security-conscious approach to building and deploying the Ocean application.

Principles​

1. Secrets Stay in CI/CD​

  • No secrets in local environments - Developers don't need production secrets
  • Source map uploads only in CI/CD - Local builds work without uploading to Sentry
  • Environment-specific secrets - Different secrets for dev, staging, and production

2. Build Process Security​

Local Development​

  • Builds run without requiring sensitive tokens
  • Sentry plugin is disabled when no auth token is present
  • Warnings are silenced for local builds to reduce noise
  • Pre-push tests validate code quality without needing secrets

CI/CD Environment​

  • Secrets are injected only during deployment
  • Source maps are uploaded only from trusted CI/CD environments
  • Environment variables are properly scoped (production vs preview)

3. What the Build Catches​

The local build process validates:

  • TypeScript compilation - No type errors
  • ESLint rules - Code quality and security patterns
  • Prettier formatting - Consistent code style
  • Bundle size - Performance considerations
  • Import structure - No circular dependencies

Security Configuration​

Vite Configuration​

sentryVitePlugin({
  // Disable when no auth token (local builds)
  disable: config.mode === 'development' || !process.env.SENTRY_AUTH_TOKEN,
  // Only upload source maps in CI/CD
  uploadSourceMaps: !!process.env.CI || !!process.env.VERCEL,
  // Silence warnings for local builds
  silent: !process.env.SENTRY_AUTH_TOKEN,
})

Environment Variables​

Required for Runtime (safe for local)​

  • VITE_SUPABASE_URL - Public Supabase URL
  • VITE_SUPABASE_PUBLISHABLE_KEY - Public key, safe to expose
  • VITE_SENTRY_DSN - Public DSN for error reporting

Required for Deployment Only (CI/CD)​

  • SENTRY_AUTH_TOKEN - For source map uploads
  • SUPABASE_SERVICE_ROLE_KEY - Backend admin access
  • STRIPE_SECRET_KEY - Payment processing
  • Database credentials

Pre-Push Validation​

The pre-push hook ensures:

  1. All tests pass - Unit and integration tests
  2. Build succeeds - Production build completes
  3. No secrets in code - Secret scanning passes
  4. Security headers configured - Vercel config includes headers

Benefits​

  1. Faster local development - No waiting for source map uploads
  2. Better security - Secrets never touch developer machines
  3. Clear separation - Runtime config vs build-time config
  4. Fail fast - Catch issues before they reach CI/CD

Troubleshooting​

"No auth token provided" warnings​

This is expected for local builds. The warnings confirm that:

  • Your local environment doesn't have production secrets (good!)
  • Source maps won't be uploaded from your machine (secure!)
  • The build will still complete successfully

Build failures in CI/CD​

Check that all required environment variables are set:

  • Vercel: Project settings → Environment Variables
  • GitHub Actions: Repository settings → Secrets
  • Supabase Edge Functions: supabase secrets list