Deploy to Vercel

On every publish, Menestrel calls your Vercel project’s Deploy Hook: Vercel rebuilds the site from the Git repository and the site reflects the published content. The hook alone is enough to trigger. To follow the deployment for real (building, live, failed), you also need an API token and the Vercel project id.

Prerequisites: a Vercel project connected to a Git repository (Deploy Hooks only exist for those), and a site wired to the Menestrel loader.

1. Create the Deploy Hook on Vercel

   In the Vercel project, open Settings > Git > Deploy Hooks. Give it a name (for example menestrel) and pick the production branch, usually main. Vercel generates a URL of the form https://api.vercel.com/v1/integrations/deploy/prj_xxx/yyy.

   Caution

   This URL grants the right to trigger builds, with no other authentication. Treat it as a secret: Menestrel encrypts it at rest and never displays it again.

2. Connect the host in Menestrel

   In the admin, open “Site settings”, the “Deployment” tab, then “Connect a host”. Pick the Vercel provider, give it a name (for example Production) and paste the URL into “Deploy hook URL”. The other fields are optional: you can already save with “Connect”.

3. Enable real status tracking (recommended)

   With nothing more, Menestrel only knows it reached Vercel: the deployment stays “Triggered”, even if the build fails afterwards. A site that silently stops rebuilding is worse than a red build. To see “Building”, “Live” or “Failed”, fill in the target’s optional fields:

   • “API token (optional, for status)”: create a token in Vercel (Account Settings > Tokens). Menestrel only uses it to read the project’s deployment list, never to act on it. Give it the narrowest possible scope and an expiration date.
   • “Project id (optional)”: in the Vercel project’s Settings > General, the prj_... value.
   • “Team id (optional)”: only if the project belongs to a team, the team_... value.

   Tracking only starts when both the API token and the project id are set.

4. Test the target

   The target’s “Test” button triggers a real build on Vercel without publishing anything new: Vercel rebuilds the site from the Git repository, with the content already published. It is not a simulation: a test that builds nothing would prove nothing. The result shows up right away: “Host reached, deployment triggered.” when the hook answered, “Test failed” with the detail otherwise.

5. Set the environment variables on Vercel

   In the Vercel project’s Settings > Environment Variables, add:

   MENESTREL_CONTENT_URL=https://content.menestrel.dev/p/prj_xxx/pk_xxx

   The loader then reads the published snapshot straight from the CDN: the build passes even if the Menestrel application is down or in maintenance. That is the nominal production path, not a degraded mode.

   MENESTREL_TOKEN exists as a fallback: the loader discovers the latest snapshot through the API. But a build that depends on a live service can break at the worst moment, so keep it for development. Resolution order is detailed in Environment variables.

Reading the states under “Recent deployments”

Every publish leaves one row per target there. With tracking enabled, the target name becomes a link to the Vercel deployment.

State	Meaning
Queued	Menestrel queued the trigger.
Triggered	The hook answered. Without tracking, the state stops here.
Building	Vercel is building the site (tracking enabled).
Live	The deployment is being served.
Failed	The Vercel build failed, or the hook stayed unreachable.
Cancelled	Deployment cancelled on Vercel, target unavailable at trigger time, or a queued trigger superseded by a more recent publish.

After repeated failures

After 3 consecutive failures, Menestrel puts the target “Paused” and stops triggering it: hammering a broken hook fixes nothing and drowns the history. Fix the cause (hook deleted on Vercel, wrong URL, expired token), then click “Resume”. The failure counter resets and publishing rebuilds the site again.