Skip to main content

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

Each Novu environment (Development, Production) has its own secret key. You sync once per environment.

Environments

Get keys from https://dashboard.novu.co/api-keys for each environment.

CLI Sync

For EU customers:

What does sync push?

  • Workflow registrations (id, name, description, tags, preferences)
  • Step definitions (id, type, control schemas, default values)
  • Payload schemas
The bridge URL is stored so Novu Cloud knows where to fetch step content at trigger time.

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 the novuhq/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

Common Issues

”Failed to reach bridge URL”

  • The bridge URL must be publicly accessible over HTTPS.
  • Auth middleware on /api/novu will 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 workflowId is 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_KEY is required even for the bridge.