supabase "project ref ... not linked" in CI

Remote Supabase commands need to know which project they target. The link is stored locally and does not exist in a fresh CI checkout. You must run supabase link --project-ref (with the DB password) before commands like db push.

What this error means

A "supabase db push" step fails with "Cannot find project ref. Have you run supabase link?" because the checkout has no linked project.

supabase

Cannot find project ref. Have you run supabase link?
Try running supabase link --project-ref <ref> first.

Common causes

The project link is not committed and CI is fresh

The link state lives in local CLI config that a clean CI checkout does not have, so the CLI does not know the target project.

The link step is missing or ran without the DB password

Linking a remote project needs the ref and the database password; skipping it or omitting the password leaves the command unable to connect.

How to fix it

Link the project before pushing

Provide the project ref and DB password as secrets.
Run supabase link --project-ref with the password from the environment.
Then run db push against the linked project.

Terminal

supabase link --project-ref "$SUPABASE_PROJECT_REF" \
  --password "$SUPABASE_DB_PASSWORD"
supabase db push

Set token, ref, and password together

Keep all three as secrets so the link and push steps have everything they need.

.github/workflows/ci.yml

env:
  SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
  SUPABASE_PROJECT_REF: ${{ secrets.SUPABASE_PROJECT_REF }}
  SUPABASE_DB_PASSWORD: ${{ secrets.SUPABASE_DB_PASSWORD }}

How to prevent it

Run supabase link at the start of every remote job.
Keep project ref and DB password in CI secrets.
Do not rely on local link state persisting into CI.