Fondoo
GitHubStart your 7-day trial for $0Start trial
Docs

Connect Netlify to Fondoo

Live4 min readUpdated

Connecting Netlify lets Fondoo set up the Netlify project that hosts your app, so it works alongside your Fondoo marketing site. Fondoo adds your app hostname to the project and sets public build variables. It also registers a signed deploy notification, so each production deploy can become changelog, blog, social and newsletter drafts for your AI agent to review.

What Fondoo can do with it

After you connect Netlify, running connect_app with host:"netlify" does three things:

  • Adds the app hostname (normally app.<your domain>) to the project. If the project has no custom domain yet, the hostname becomes its custom domain. Otherwise it is added as a domain alias. Your existing domain and aliases are always kept.
  • Sets build environment variables. It sets FONDOO_SITE_ID and FONDOO_API_BASE, each with the prefixes NEXT_PUBLIC_, VITE_, PUBLIC_ and NUXT_PUBLIC_. They apply to the production deploy context with the builds scope. If a variable already exists, only its production value is changed. These values are public, not secrets.
  • Registers a signed deploy notification. Fondoo is notified for the "deploy succeeded" event.

After that:

  • get_connection_health checks the project.
  • Verified production deploys enter Fondoo's release-content pipeline. Other deploy contexts are ignored, and duplicates are dropped.

Fondoo does not start deploys, edit code or merge pull requests. Saving the Netlify token is owner-only. connect_app is a normal write that agents can run.

Before you start

  • A Netlify account and the project (formerly "site") that hosts your app. Netlify's Free plan works for the basics.
  • Plan limits may apply to environment variables. Netlify's API reference marks granular variable scopes as "Pro plans and above" (Netlify API). Fondoo sets the builds scope, so the variable step may be refused on the Free plan. This may differ for your account.
  • A Fondoo site and your app's public URL, for example https://my-app.netlify.app.
  • Owner access in Fondoo to save the token.

Step by step: get your credentials

You need three values: a personal access token, the project ID and the account (team) ID.

  1. Create a personal access token.
    1. Open your user settings, then Applications → Personal access tokens: https://app.netlify.com/user/applications#personal-access-tokens .
    2. Select New access token and enter a name, for example "Fondoo".
    3. If your team uses SAML single sign-on, tick Allow access to my SAML-based Netlify team.
    4. Pick an Expiration, then select Generate token.
    5. Copy the token now. It is shown only once. Then select Done (get started with the API).
    A personal token acts with your full user permissions; Netlify does not offer finer scopes. Consider creating it from a team member account that only has access to the relevant team.
  2. Find the project ID. Open the project, then Project configuration → General → Project details → Project information and copy Project ID. Older screens and the API call it the "site ID". In Fondoo it goes in the projectId field.
  3. Find the account ID. In the API, "account" means your team. Open Team settings → General → Team details → Team information and copy the team slug. Netlify accepts the slug wherever an account ID is required. Fondoo requires this value for Netlify.

Connect it in Fondoo

In the dashboard:

  1. Open Connections.
  2. Under Available → Development, find Netlify and click Connect Netlify.
  3. Connect securely opens a 15-minute guide page. It does not collect the token.
  4. Save the token with configure_host_connection, as below.

By asking your agent. For example:

"Hook up my Netlify app https://my-app.netlify.app to Fondoo."

The agent can send you a guide link with connect_service({provider:"netlify", siteId}). Then you, as owner, run:

configure_host_connection({siteId, provider:"netlify", projectId:"<project ID>", accountId:"<team slug>", token:"<token>"})

The agent then calls:

connect_app({siteId, appUrl:"https://my-app.netlify.app", host:"netlify"})

This flow does not use the add_connection_key secure paste page. The token is part of the call, so do not paste it into a chat. Use REST from your own terminal:

POST https://api.getfondoo.com/v1/ops/configure_host_connection
Authorization: Bearer <owner credential>
{"siteId":"...","provider":"netlify","projectId":"...","accountId":"my-team","token":"..."}

Fondoo reads the project once before saving. A bad token or project ID fails immediately.

Webhooks

connect_app registers the deploy notification through Netlify's API. You do not add it by hand.

  • URL: https://api.getfondoo.com/webhooks/hosts/<connectionId>
  • Event: deploy succeeded
  • Signing: Fondoo generates a random secret and gives it to Netlify as the JWS secret. Netlify then sends an X-Webhook-Signature header: a JSON Web Signature (HS256) whose claims include iss: "netlify" and a SHA-256 hash of the body (deploy notifications). Fondoo checks the signature, the issuer and the body hash, and rejects anything that does not match.
  • Only deploys in state ready in the production context are used.

You can see the notification under Project configuration → Notifications → Deploy notifications. Do not edit its secret: Fondoo would then reject every delivery.

Test that it works

  1. Run get_connection_health({siteId}) and look for a recent Netlify success.
  2. In Netlify, check Project configuration → Environment variables for NEXT_PUBLIC_FONDOO_SITE_ID and the others.
  3. In Domain management, confirm the app hostname, then add the DNS records from the connect_app routing plan and wait for HTTPS.
  4. Trigger a production deploy, then check get_release_content. This needs release jobs enabled on your Fondoo server.

Troubleshooting

  • "Netlify accountId is required". Add the team slug as accountId.
  • "Host request failed (401)". The token is wrong, expired or revoked. Generate a new one.
  • "Host request failed (404)". Check the project ID. It must belong to a team the token can see.
  • Environment variable step fails (400/403). The scope options may need a paid plan, or your user cannot edit team variables. Check your plan and role.
  • The deploy notification is not created. Your plan or role may not allow it. This may differ for your account; contact your Fondoo operator with the error.
  • "Host request failed (429)". Netlify allows about 500 API requests per minute. Wait and retry.

Limits, data and security

  • What Fondoo stores: the token and webhook secret, encrypted, plus the project and team IDs and the last success or error. Neither secret is shown back.
  • Rotate: generate a new token and run configure_host_connection again for the same project. The existing notification is kept. Changing to a different project clears it so connect_app can register a new one.
  • Disconnect: Fondoo has no operation that removes a host connection. To stop access:
    1. Delete the token on the Personal access tokens page.
    2. Remove the deploy notification.
    3. Optionally, remove the FONDOO_ variables and the domain alias.