Deploy to Netlify

This guide connects Netlify as a deploy target for a Menestrel project. On every publish (and every version restore), Menestrel calls the Build Hook: Netlify rebuilds your Astro site, which picks up the published snapshot. The hook alone is enough to rebuild; add an API token and the admin follows each build all the way to “Live” or “Failed”.

Prerequisites: a Netlify site that already builds your Astro project from Git, and a synced Menestrel project (see Your first site).

Caution

Without a connected host, publishing does produce a snapshot, but no site gets rebuilt. The published content stays invisible until the next build. Connecting the target is part of going to production, not a finishing touch.

1. Create the Build Hook on Netlify

   In Netlify, open your site, then Site configuration, Build & deploy, Build hooks, and add a hook. Name it menestrel, pick the production branch, then copy the generated URL:

   https://api.netlify.com/build_hooks/xxxxxxxxxxxxxxxxxxxxxxxx

   Menestrel only accepts https URLs on the api.netlify.com host. Anything else is rejected when the target is created.

2. Connect the target in Menestrel

   In the admin, open “Site settings”, the “Deployment” tab, then “Connect a host”. Pick the Netlify provider, name the target (for example “Netlify prod”) and paste the hook URL into the “Deploy hook URL” field. The two other fields are optional: without them, the target already rebuilds the site.

3. Enable build tracking (optional)

   Without a token, Menestrel triggers the build and hears nothing back: the deployment stays “Triggered” in the list. With tracking, it moves through “Building” to “Live” or “Failed”, with a link to the Netlify deploy URL. Fill in both fields, one without the other is not enough:

   • “API token”: a Netlify Personal Access Token (User settings, Applications, Personal access tokens). Menestrel only uses it for reads, to list the site’s deploys.
   • “Site id”: your site’s Site ID, shown under Site configuration, General.

   The target configuration, token included, is encrypted at rest.

4. Test the target

   The “Test” button really calls the hook: Netlify runs an actual build. That is deliberate, a test that triggers nothing proves nothing. In the Netlify deploys list, the build shows up titled Publication Menestrel: <snapshot id>, or Publication Menestrel: test if nothing is published yet.

5. Set the build environment variables

   In Netlify (Site configuration, Environment variables), set MENESTREL_CONTENT_URL to the published snapshot URL:

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

   The build then no longer depends on the Menestrel application: if the admin is down for maintenance, Netlify still rebuilds. Do not set MENESTREL_TOKEN in production. Full variable list: Environment variables.

What Menestrel sends to Netlify

On every trigger, Menestrel sends a POST to the hook with a trigger_title URL parameter set to Publication Menestrel: <snapshot id>, and a JSON body of {"snapshot_id": "..."}. Every build is therefore identifiable in the Netlify deploys list: you always know which publish produced which build.

With tracking enabled, Menestrel polls GET https://api.netlify.com/api/v1/sites/<site_id>/deploys with the token: first 15 seconds after the trigger, then at widening intervals up to one minute, for at most 45 minutes. The Netlify states new, enqueued, building and processing show as “Building”; ready becomes “Live”; error becomes “Failed”.

Repeated failures: pausing

A failed trigger is retried, at most three attempts per build. After three consecutive failures, the target switches to “Paused”: Menestrel stops calling a hook that no longer answers, rather than failing silently on every publish. Fix the cause (hook deleted on Netlify, revoked token…), then click “Resume” on the target.