Skip to content

docs(operations): deploy prerequisites learned the hard way #79

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
BluegReeno merged 1 commit into from
Jul 26, 2026
Merged

docs(operations): deploy prerequisites learned the hard way #79

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions docs/operations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,34 @@ The token is loaded per-directory by `direnv` from `/Users/renaud/Projects/hal/.
supabase projects list # the row shows ● in the LINKED column when authed + visible
```

**direnv does not fire in a non-interactive shell.** An agent, a script, a CI runner or anything
driving `make deploy` without an interactive `cd` gets **no token at all** and falls through to
the personal account — which fails with a 403 that reads like a permissions problem rather than a
missing token. Source it explicitly first, exactly as Path B does:

```bash
source /Users/renaud/Projects/hal/.envrc
```

### CLI version prerequisite

`supabase/functions/hal-mcp/deno.lock` is **lockfile version 5** (since `c19bec9`, June 2026).
The Deno bundled in older CLI releases cannot read it, and the deploy dies *after* auth succeeds:

```
Error: Failed reading lockfile at '.../deno.lock'
Caused by: Unsupported lockfile version '5'. Try upgrading Deno or recreating the lockfile
```

**Do not delete or regenerate `deno.lock` to work around this** — it pins the exact dependency
versions that ship to production. Upgrade the CLI instead (2.72.7 → 2.109.1 fixed it on
2026-07-25):

```bash
brew trust --formula supabase/tap/supabase # Homebrew now refuses untrusted taps
brew upgrade supabase
```

### Pre-deploy check (non-negotiable)

`supabase/functions/hal-mcp/index.ts` **must** end with:
Expand All @@ -123,6 +151,20 @@ an unauthenticated call must be rejected (401/400/405) by a live function. `make
offline counterpart (deno type-check both edge functions + offline pytest) for pre-deploy sanity
before ever reaching the live probe.

⚠️ **`make test` does not run the `hal-mcp` unit tests, and neither does CI** (see #78). It
type-checks. To actually exercise `index.test.ts` before a deploy — worth doing whenever the
deploy carries a behavioural change:

```bash
cd supabase/functions/hal-mcp
SUPABASE_URL="https://zgkvbjqlvebttbnkklpo.supabase.co" \
SUPABASE_SECRET_KEYS='{"default":"test-admin"}' \
deno test --allow-all index.test.ts # ok | 63 passed | 0 failed
```

`SUPABASE_URL` must be the **real** project URL: four OAuth-metadata tests assert the exact
`resource_metadata` value, so a placeholder fails those four while the other 59 pass.

### Path A — deploy from `main` (the normal case)

```bash
Expand Down
Loading