{
  "name": "deploy",
  "title": "Deploy Pipeline & gipity.yaml",
  "description": "The deploy pipeline: gipity.yaml manifest, phases, dev vs prod, checksums, and reading phase results",
  "guid": "sk_plat_dply",
  "category": "App development",
  "requiredTools": [
    "project_deploy"
  ],
  "content": "# Deploy Pipeline & gipity.yaml\n\n`gipity deploy` pushes your project live. It runs a multi-phase pipeline server-side and is the step most likely to surface mistakes - so deploy early and often, and **read the phase results every time**.\n\n## The build loop\n\n```\ngipity add → edit files → gipity deploy dev → gipity page-inspect <url> → fix errors → repeat\n```\n\nDeploy to `dev` while building; deploy to `prod` only when it works. See [app-debugging](app-debugging.md) for the inspect step.\n\n## Commands\n\n```bash\ngipity deploy dev      # → https://dev.gipity.ai/<account>/<project>/\ngipity deploy prod     # → https://app.gipity.ai/<account>/<project>/\n```\n\n| Flag | Effect |\n|---|---|\n| `--only <phases>` | Run only these phases, comma-separated (e.g. `--only database`) |\n| `--force` | Re-run every phase, ignore checksums |\n| `--optimize` | Run build optimization on static files |\n| `--source-dir <dir>` | Deploy from a directory other than the project root |\n| `--no-sync` | Skip the sync-up that normally runs before deploy |\n| `--json` | Machine-readable output (the `phases` array) |\n\n## gipity.yaml - the deploy manifest\n\nA project **without** `gipity.yaml` gets a plain static-file deploy (the `src/` folder → CDN). A project **with** `gipity.yaml` gets the full multi-phase pipeline. The `web-fullstack` and `api` starters ship one; `web-simple` does not.\n\n```yaml\nversion: 1\n\ndeploy:\n  phases:\n    # Static frontend → CDN\n    - name: files\n      type: static\n      source: src\n\n    # SQL migrations → user database (idempotent, each runs once)\n    - name: database\n      type: sql\n      source: migrations\n      database: {{DATABASE}}\n\n    # Serverless functions → HTTP endpoints\n    - name: functions\n      type: functions\n      source: functions\n      function_definitions:\n        - name: get-weather\n          auth: public\n          fetch_domains: [api.open-meteo.com]\n          tables: [weather_lookups]\n```\n\n### Phases\n\n| Phase `type` | Source | What it does |\n|---|---|---|\n| `static` | `src/` | Uploads frontend files to the CDN |\n| `sql` | `migrations/` | Auto-creates the database, runs each migration once, loads seeds - idempotent |\n| `functions` | `functions/` | Deploys each `.js` file as an HTTP endpoint with its declared permissions |\n\nWorkflow automations are also tracked as a phase when present.\n\n### function_definitions\n\nFunctions auto-deploy as **public** endpoints, and the deploy pipeline **auto-adds an entry** to `gipity.yaml` for any function it finds undeclared. You only edit entries to grant more than the default:\n\n| Field | Purpose |\n|---|---|\n| `name` | Function file name (without `.js`) |\n| `auth` | `public` (no auth), `user` (logged-in), `member` (project member) |\n| `tables` | Database tables the function may read/write |\n| `fetch_domains` | External hosts the function may `fetch` - **required** to call app services like `a.gipity.ai` |\n| `services` | Declared app services (`llm`, `location`, ...) - documentation only; services are still called via `fetch` |\n\n## Checksums - phases skip when unchanged\n\nOn re-deploy, a phase whose inputs haven't changed is skipped (you'll see it reported as unchanged). Use `--force` to re-run everything, or `--only <phase>` to target one phase.\n\n## Read the phase results - every deploy\n\nEach phase reports a status. Do not move on until they're all clean:\n\n| Status | Meaning | Action |\n|---|---|---|\n| `ok` ✓ | Phase succeeded | None |\n| `warning` ⚠ | Deprecated or mis-shaped input (usually `gipity.yaml`); summary starts with \"FIX\" | Treat as a TODO - fix the file and redeploy |\n| `failed` ✗ | Phase did not complete | Fix before doing anything else - the deploy did not fully land |\n\nA `warning` is not informational. Leaving it unresolved means something is already broken or about to be.\n\n## Related skills\n\n- [app-debugging](app-debugging.md) - inspect the deployed page and read function logs\n- [app-development](app-development.md) - writing the functions, database, and tests that the pipeline deploys\n"
}