> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cubby.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy Verification

> How Cubby validates your code before and after deployment

# Deploy Verification

Every deploy goes through a 3-phase verification pipeline. Checks can pass, warn, or fail. **Failures block deployment.** Warnings are informational. Some issues are auto-fixed by Cubby.

## Phase 1: Pre-Build Checks

Pre-build checks run on your source code before the Docker image is built. All four checks run concurrently.

### Blocked Dependencies

Detects payment and authentication libraries that conflict with Cubby's built-in features.

**Blocked payment libraries** (Cubby does not support in-app payment processing):

* `stripe`, `@stripe/stripe-js`, `@stripe/react-stripe-js`
* `@paypal/checkout-server-sdk`, `@paypal/react-paypal-js`
* `@lemonsqueezy/lemonsqueezy.js`, `@paddle/paddle-js`
* `braintree`, `square`, `revenuecat`

**Blocked auth libraries** (Cubby provides built-in SSO):

* `next-auth`, `@auth/core`, `@auth/nextjs`
* `@clerk/nextjs`, `@clerk/backend`
* `passport`, `passport-local`, `passport-jwt`
* `lucia`, `@lucia-auth/adapter-prisma`
* `better-auth`, `@supabase/auth-helpers-nextjs`

If found in your `package.json` dependencies or devDependencies, the deploy is blocked with a `fail` status.

### Secret Detection

Scans your source files for committed API keys, tokens, and private keys. Uses pattern matching for known secret formats:

* **High confidence** (blocks deploy): AWS access keys (`AKIA...`), Stripe live keys (`sk_live_...`), GitHub tokens (`ghp_...`), Anthropic keys (`sk-ant-...`), OpenAI keys (`sk-...`), private key blocks (`-----BEGIN PRIVATE KEY-----`), and more
* **Medium confidence** (warning only): Generic patterns like `api_key = "..."` assignments

The scanner skips `node_modules`, `.next`, `dist`, `.git`, binary files, and `.env.example` files.

<Tip>
  Use `cubby secrets set` to store API keys securely instead of committing them to your code.
</Tip>

### Project Structure

Validates that required files exist and configuration is correct:

* **package.json**: Required. Deploy fails if missing.
* **cubby.yaml**: Recommended. Warning if missing or malformed. Must contain a `name` field.
* **Dockerfile**: If present, validated for security. Must include a non-root `USER` instruction. Dangerous patterns are flagged.

### Service Worker Cache Versioning

Scans for service worker files (`sw.js`, `service-worker.js`, and their `.ts` variants) and checks if they use static cache names.

If your service worker calls `caches.open('my-cache')` with a hardcoded string (no version or hash), you get a **warning**. Static cache names cause stale UI after redeploy, especially on iOS Safari PWAs.

See [PWA Support](/platform/pwa) for how to version your cache names.

## Phase 2: AI Review

A two-pass AI pipeline reviews your source code for security, content, authentication, and PWA issues.

### Pass 1: Haiku (Fast Scan)

Claude Haiku scans your source files for common issues. This is a quick pass that covers:

* **Security**: Code vulnerabilities, dangerous patterns
* **Content**: Inappropriate or problematic content
* **Auth integration**: Correct usage of Cubby auth headers
* **PWA compliance**: Manifest and service worker issues

If Haiku finds nothing, the review is complete and the deploy continues.

### Pass 2: Sonnet (Escalation)

If Haiku flags any issues, Claude Sonnet performs a deeper review to confirm or dismiss each finding. This reduces false positives -- Sonnet may dismiss findings that Haiku flagged.

Confirmed findings are reported as:

* **block**: Critical issue, deploy is blocked
* **warn**: Advisory, deploy proceeds
* **dismiss**: False positive, no action needed

### PWA Auto-Fix

As part of the AI review phase, Cubby runs a deterministic (non-AI) check on your PWA assets:

* **Missing manifest.json**: Generates one with your app name, theme color, display mode, and icons
* **Missing icons**: Generates 192x192 and 512x512 PNG icons with a color derived from your app name
* **Missing manifest link**: Warns if your layout file lacks a `<link rel="manifest">` tag

Auto-fixed items appear in your deploy report with status `fixed`.

### AI Cost Transparency

Each AI review reports the model used and token counts, so you can see the cost of the review in your deploy report.

## Phase 3: Post-Build Checks

Post-build checks run after your Docker image is built and the container starts.

### Health Check

Sends an HTTP GET request to the root path (`/`) of your running container. Expects an HTTP 200 response within 30 seconds.

If the health check fails:

* Container startup logs are captured for debugging
* The deploy is blocked
* The error message includes the logs to help you diagnose the issue

### Manifest Validation

If the HTTP health check passes, Cubby also checks that `manifest.json` is accessible and valid at the running app URL. A missing or invalid manifest produces a **warning** (not a failure) -- your app still deploys, but PWA install may not work correctly.

## Check Statuses

| Status  | Meaning                    | Deploys?       |
| ------- | -------------------------- | -------------- |
| `pass`  | Check passed               | Yes            |
| `warn`  | Advisory issue found       | Yes            |
| `fail`  | Critical issue found       | No             |
| `fixed` | Issue auto-fixed by Cubby  | Yes            |
| `error` | Check itself failed to run | Yes (degraded) |

The overall deploy status is determined by the worst individual check status: any `fail` or `error` blocks the deploy. Warnings and fixes allow it to proceed.

## Viewing Results

Verification reports are shown in the CLI during `cubby deploy`:

```
Verification Report
-------------------
Pre-Build Checks:
  blocked-dependencies ............ PASS
  secret-detection ................ PASS
  structure-package-json .......... PASS
  structure-cubby-yaml ............ PASS
  sw-cache-versioning ............. PASS

AI Review:
  PWA Manifest .................... FIXED (generated manifest.json and icons)
  AI Review (haiku) ............... PASS

Post-Build Checks:
  http-health ..................... PASS
  manifest-json ................... PASS
```

Reports are also available in the [dashboard](https://app.cubby.pro) under each app's deploy history.

## Related

* [PWA Support](/platform/pwa) - PWA features and caching best practices
* [`cubby check`](/cli-reference/check) - Run pre-build checks locally
* [`cubby deploy`](/cli-reference/deploy) - Deploy with verification