Deployment
@novu/framework operates in a GitOps model — your workflows live in source control, and a sync step pushes them to Novu Cloud after each merge.
The flow
Environments
Get keys from
https://dashboard.novu.co/api-keys for each environment.
CLI Sync
What does sync push?
- Workflow registrations (id, name, description, tags, preferences)
- Step definitions (id, type, control schemas, default values)
- Payload schemas
Sync via Vercel Preview
Free-tier preview URLs are deployment-protected by default. Enable Protection Bypass for Automation in your Vercel project settings, then pass the bypass token in the bridge URL:GitHub Actions
Use thenovuhq/actions-novu-sync@v2 action.
Production sync on main
Development sync on PR
Inputs
Other CI/CD
All other CI tools can use the CLI directly. Examples:GitLab CI
CircleCI
Jenkins
Bitbucket Pipelines
Azure DevOps
Travis CI
Recommended Pipeline Structure
Common Issues
”Failed to reach bridge URL”
- The bridge URL must be publicly accessible over HTTPS.
- Auth middleware on
/api/novuwill block Novu — exempt that path. - Vercel preview URLs require Protection Bypass — see above.
”Invalid secret key”
You’re syncing with the wrong environment’s key. Each Novu environment has its own key — don’t mix Dev and Prod.Workflows don’t appear in Dashboard after sync
- Check the sync command exited 0 — failures may be silent in some CI environments.
- Make sure your bridge actually returns the workflow on
GET /api/novu— Novu fetches the registration list from there. - If you renamed a workflow, the old
workflowIdis not auto-deleted. Delete it manually in the Dashboard if needed.
Sync succeeded but triggers fail
- The bridge URL stored in Novu Cloud is wrong — re-sync with the correct URL.
- Production env vars are missing on your deployed app —
NOVU_SECRET_KEYis required even for the bridge.