Sites - automation and deploy pipelines

Sites does more than "upload and publish": every deployment can go through a pipeline with tests, a quality gate, approval and automatic rollback. Define it in the dashboard (the Pipeline tab) or as code in hostbase.json.

New site wizard

• Import from Git - repositories visible to the project's GitHub connection (private ones too; the connected repo gets push-to-deploy) or any public URL on github.com, gitlab.com, bitbucket.org or codeberg.org (including /tree/branch/subdir). Archives up to 24 MB.
• Upload files - drag a folder (we skip node_modules, .git, .next) or a .zip / .tar.gz.
• Templates - 20+ starters (Next.js with Supabase auth, SaaS, a Stripe shop, Astro, SvelteKit, Nuxt, Vite React/Vue/Solid/Svelte, VitePress, Docusaurus, Eleventy, Hono, Express…).
• We detect the framework, package manager (npm, pnpm, yarn, bun), Node version and monorepos (you pick the app directory). Everything is editable. Variables can be imported from a .env file; Supabase keys are injected automatically.
• The last step shows a live build log and deployment progress.

The deploy pipeline

1. Build - preBuild (after install) and postBuild are shell commands in the build container (gVisor). The build cache (.next/cache, .astro, .svelte-kit, node_modules/.cache, …) is kept between builds per site (up to 1 GB per directory); the log shows "build cache restored".
2. Checks (optional) - Lighthouse and visual diff on the deployment URL.
3. preDeploy gate - steps: smoke (HTTP status / text), sql (a migration against the project database), script (a command in a container) and webhook. While the gate runs the deployment is only a preview; a failure leaves production untouched.
4. Approval (requireApproval) - an owner or admin approves the promotion in the dashboard or with hostbase sites approve.
5. Promotion and postDeploy steps against the production URL. A failing test triggers an automatic rollback to the previous deployment plus a notification.
6. 5xx watch (autoRollback) - for minutes minutes we compare 5xx responses with requests after promotion (from Traefik logs); crossing errorRate with at least minRequests requests rolls back.

{
  "sites": {
    "web": {
      "framework": "nextjs",
      "pipeline": {
        "preBuild": ["npm run lint"],
        "postBuild": [],
        "cache": true,
        "preDeploy": [
          { "name": "Migracja", "sql": "alter table public.posts add column if not exists slug text;" },
          { "name": "Podgląd działa", "smoke": { "path": "/", "status": 200 } }
        ],
        "postDeploy": [
          { "smoke": { "path": "/", "status": 200, "contains": "Hello" } },
          { "smoke": { "path": "/api/health", "status": 200 } }
        ]
      },
      "triggers": {
        "productionBranch": "main",
        "previewBranches": ["feat/*"],
        "prPreviews": true,
        "schedule": "0 3 * * *",
        "onSchemaChange": false,
        "requireApproval": false
      },
      "autoRollback": { "enabled": true, "errorRate": 0.05, "minutes": 10, "minRequests": 20 },
      "checks": { "lighthouse": true, "visual": true, "minScores": { "performance": 70, "accessibility": 90 }, "gate": false },
      "scripts": [{ "name": "sitemap", "command": "node scripts/sitemap.mjs", "schedule": "30 4 * * *" }],
      "notify": { "onFailure": true, "onRollback": true, "webhook": null }
    }
  }
}

A hostbase.json at the root of the archive (GitHub, hostbase sites deploy, the wizard) is read on every source deployment and replaces the sections it defines. Build settings in the file: framework, installCommand, buildCommand, outputDir, rootDir, startCommand, node, spa. The "*" key under sites applies to every site. Starter file: hostbase sites init.

Triggers

• Push to productionBranch deploys production; a push to branches matching previewBranches (e.g. feat/*) creates a preview with its own URL.
• Pull requests from the same repository get a preview, a commit status and a comment with the URL and Lighthouse scores (prPreviews).
• Deploy hook (POST …/api/hooks/sites/<token>) and the API/CLI.
• Schedule (schedule, 5-field cron in UTC) - e.g. a nightly rebuild of a static site generated from your database.
• Schema change (onSchemaChange) or Storage bucket change (onStorageChange) - we check a signature every 5 minutes.
• Approvals - with requireApproval only owners/admins can also promote deployments manually.

Scripts and jobs

Scripts (scripts) are commands run in the build image on the source of the latest deployment: regenerate a sitemap, purge or warm caches, imports. They can have a schedule. Results and logs are kept in the history on the Scripts tab. A script never receives the service_role key unless an owner/admin explicitly allows it.

Quality checks

Lighthouse (performance, accessibility, SEO, best practices; mobile or desktop), a screenshot and a pixel diff against production (pixelmatch) in headless Chromium inside a separate, isolated container. Results appear in the deployment list, on the Checks tab and in the PR comment. minScores thresholds warn; with gate: true they block promotion.

Environment groups

Besides shared variables there are production, preview and development groups (secrets are masked). Production deployments receive the production group, previews and PRs the preview group. For local work, hostbase sites env pull web --group development writes .env.local with the Supabase keys, shared variables and the group.

Web Vitals (opt-in)

Analytics → Web Vitals: once enabled you get a <script defer src="…/api/rum/<key>/v.js"> snippet (~1 KB, no cookies). We measure LCP, INP, CLS, FCP and TTFB per path.

CLI

hostbase sites init web                              # starter hostbase.json
hostbase sites config push web                       # apply hostbase.json
hostbase sites config pull web                       # write the dashboard config to the file
hostbase sites pipeline web                          # pipeline runs with their steps
hostbase sites approve web pr_ab12cd34ef56           # approve a promotion
hostbase sites scripts run web sitemap               # a configured script (live log)
hostbase sites scripts run web --command "npm run purge"
hostbase sites checks run web --deployment d12       # Lighthouse + screenshot + diff
hostbase sites env pull web --group development      # .env.local
hostbase sites env group web preview API_URL=https://staging.example --secret
hostbase sites rum web on

API and MCP

GET|PUT /api/v1/projects/{ref}/sites/{name}/auto/automation
GET|PUT /api/v1/projects/{ref}/sites/{name}/auto/env-groups        # ?reveal=1
GET     /api/v1/projects/{ref}/sites/{name}/auto/env-pull?group=development
GET     /api/v1/projects/{ref}/sites/{name}/auto/pipeline-runs
POST    /api/v1/projects/{ref}/sites/{name}/auto/pipeline-runs/{id}/approve|reject
GET|POST /api/v1/projects/{ref}/sites/{name}/auto/scripts          # {script} | {command}
GET|POST /api/v1/projects/{ref}/sites/{name}/auto/checks           # {deployment, form_factor}
GET     /api/v1/projects/{ref}/sites/{name}/auto/runs/{id}[/shot.png|diff.png|base.png]
GET|PUT /api/v1/projects/{ref}/sites/{name}/auto/rum

MCP tools: site_automation, site_env_groups, site_pipeline_runs, site_scripts, site_checks, site_rum.

Billing

Scripts, Lighthouse checks and screenshots consume Sites build minutes (container run time), like regular builds. A Lighthouse check usually takes about a minute; overview thumbnails are short captures (a few seconds) taken once per production deployment. Failure, rollback and approval notifications go to the bell and to organisation channels (Slack, Discord, e-mail, webhook).