Preview Deployments

Every pull request targeting main automatically gets a live preview deployment with an isolated database, so QA agents and reviewers can test against a real URL without touching production data.

How it works

1. Build & type check passes (the build job in ci.yml)
2. A dedicated D1 database named nucleus-preview-pr-{number} is created (or reused if it already exists)
3. All database migrations are applied to the preview database
4. The Worker is deployed as a preview version aliased to pr-{number}, bound to the isolated D1
5. A comment is posted on the PR with the preview URL

When the PR is closed (merged or abandoned), the cleanup workflow deletes the preview D1 database and removes the Worker version alias.

Preview URL

https://pr-{number}.nucleus-app.workers.dev

Workflows

Workflow	File	Trigger
CI + Preview Deploy	.github/workflows/ci.yml	PR opened or updated
Preview Cleanup	.github/workflows/preview-cleanup.yml	PR closed

Required GitHub Actions Secrets

These secrets must be configured in the repository settings under Settings → Secrets and variables → Actions:

Secret	Description
CLOUDFLARE_API_TOKEN	Cloudflare API token with Workers, D1, and Account permissions. Generate at dash.cloudflare.com/profile/api-tokens using the Edit Cloudflare Workers template, then add D1 read/write permissions.
CLOUDFLARE_ACCOUNT_ID	Your Cloudflare account ID. Found in the Cloudflare dashboard URL or on the Workers & Pages overview page.

Caution

Do not commit these values to the repository. They must only be stored as GitHub Actions secrets.

D1 Isolation

Each preview PR gets its own nucleus-preview-pr-{number} D1 database. This means:

• Preview data is completely separate from production
• Multiple PRs can run simultaneously without interfering with each other
• Migrations are validated against a real database before merging
• The preview database is deleted when the PR closes

Limitations

• Preview deployments require the CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID secrets to be configured. If they are missing, the preview job will fail but the build job will still run.
• R2 bucket bindings (UPLOADS) and Analytics Engine (ANALYTICS) still point to the production bindings in preview mode — only the D1 database is isolated.
• AI binding (AI) uses the shared Cloudflare AI gateway.