Netlify

What it does

• Pull at build: the build command runs stoaken export first, so every deploy ships the live release's tokens.
• Push on publish: a standard Stoaken webhook calls a Netlify build hook. A build hook takes a POST with no authorisation, and any body it gets is passed to the build as INCOMING_HOOK_BODY (docs), so a published release rebuilds the site. See /docs/webhooks.

Before you start

• A Stoaken API key and a stoaken.config.json with exports (see /docs/cli).
• A Netlify project that builds from a Git repository, with builds active. Build hooks don't start builds while builds are stopped.
• Brand Admin in Stoaken, on the Team plan, for the webhook part.

Setup

1. Add an environment variable STOAKEN_TOKEN (your API key) to the project. Its scope must include Builds, or the build can't read it (docs). Keep it out of netlify.toml.
2. Make the build export first in netlify.toml (template: netlifyToml() in src/lib/integrations/pipelines.ts):

# Stoaken: export the live tokens before every build.
# STOAKEN_TOKEN goes in Project configuration > Environment variables (scope: Builds), not here.
[build]
  command = "npx --yes stoaken@latest export && npm run build"

[build.environment]
  NODE_VERSION = "22"

3. Under Project configuration > Developer settings > Continuous deployment > Build hooks, choose Add build hook, name it (for example Stoaken), pick the branch to build, and copy the URL.
4. In Stoaken, choose Add a webhook, set Send as to Stoaken event, paste the hook URL as the address, and pick Release published.

Configuration

• Settings in netlify.toml override the same settings in the Netlify UI (docs). If you keep the build command in the UI instead, put npx --yes stoaken@latest export && in front of it there.
• Add ?trigger_title=Stoaken+release+published to the hook URL so the deploy list says why it built. trigger_branch builds another branch, and clear_cache=true builds without the cache. The export doesn't depend on the cache.
• The release's JSON arrives in INCOMING_HOOK_BODY, but the export doesn't need it. It reads the live release itself.
• If you also commit token files, add npx stoaken export --check to your Git provider's CI (see the GitHub, GitLab or Bitbucket guide) rather than to the Netlify build.

Try it

1. Send test should get a 2xx from Netlify and start a deploy named after the hook. Netlify doesn't read the body, so a test builds for real.
2. The deploy log shows the stoaken export lines.

Troubleshooting

• Build fails at export with 401: STOAKEN_TOKEN is missing, its scope leaves out Builds, or the key was revoked.
• No deploy: builds are stopped for the project, or the hook was deleted. Make a new hook and update the webhook's address.
• Build fails straight away: the hook's branch (or trigger_branch) doesn't exist in the repository. The build log says so.
• The UI build command is ignored: netlify.toml has a command, and the file wins.

Limits

• A build hook rebuilds one branch. It doesn't change your repository.
• Anyone with the hook URL can start a build. Brand Admins can see it in Stoaken, so delete and replace the hook if it leaks.
• Every delivery starts a build and uses build minutes, including retries Stoaken makes after a failed attempt.