⚙️ Supabase CLI Action

About

This composite action sets up the Supabase CLI, supabase, on GitHub's hosted Actions runners. Other CI runners like Bitbucket and GitLab are supported via their respective pipelines.

This action can be run on ubuntu-latest, windows-latest, and macos-latest GitHub Actions runners, and will install and expose a specified version of the supabase CLI on the runner environment.

Usage

Setup the supabase CLI:

steps:
  - uses: supabase/setup-cli@v3

If version is omitted, the action checks the repository root for bun.lock, pnpm-lock.yaml, or package-lock.json and installs the declared supabase package version through npm. If the lockfile includes package integrity metadata, the action verifies it against the npm registry before installing. If no supported lockfile is present, it falls back to latest.

The action uses an existing Node.js/npm runtime when one is already available, and requires Node.js 20 or newer. On non-musl runners without Node.js or npm, it provisions them internally. Runners must be able to reach the npm registry to install the CLI package.

When running in Alpine or other Linux musl containers, the action uses Alpine's nodejs and npm packages instead of actions/setup-node, because the standard Node.js runner binaries target glibc. Root containers can have missing runtime packages installed automatically. Non-root containers must include Node.js 20+ and the runtime packages in the image before the action runs:

FROM alpine:3.20

RUN apk add --no-cache libstdc++ libgcc nodejs npm

USER 1000:1000

A fixed npm-published version, latest, or beta of the supabase CLI can be installed:

steps:
  - uses: supabase/setup-cli@v3
    with:
      version: 2.84.2

steps:
  - uses: supabase/setup-cli@v3
    with:
      version: beta

Run supabase db start to execute all migrations on a fresh database:

steps:
  - uses: supabase/setup-cli@v3
    with:
      version: latest
  - run: supabase init
  - run: supabase db start

Since Supabase CLI relies on Docker Engine API, additional setup may be required on Windows and macOS runners.

Inputs

The action supports the following inputs:

Name	Type	Description	Default	Required
version	String	Supabase CLI latest, beta, or fixed version published to npm	Root lockfile version or latest	false

Advanced Usage

Check generated TypeScript types are up-to-date with Postgres schema:

steps:
  - uses: supabase/setup-cli@v3
  - run: supabase init
  - run: supabase db start
  - name: Verify generated types match Postgres schema
    run: |
      supabase gen types typescript --local > schema.gen.ts
      if ! git diff --ignore-space-at-eol --exit-code --quiet schema.gen.ts; then
        echo "Detected uncommitted changes after build. See status below:"
        git diff
        exit 1
      fi

Release job to push schema changes to a Supabase project:

env:
  SUPABASE_ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
  SUPABASE_DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
  # Retrieve <project-id> from dashboard url: https://app.supabase.com/project/<project-id>
  PROJECT_ID: <project-id>

steps:
  - uses: supabase/setup-cli@v3
  - run: supabase link --project-ref $PROJECT_ID
  - run: supabase db push

Export local Supabase env vars for app tests:

steps:
  - uses: supabase/setup-cli@v3
  - run: supabase init
  - run: supabase start
  - name: Export local Supabase env vars
    run: |
      # Customize the variable names as needed for your app.
      supabase status -o env \
        --override-name api.url=SUPABASE_URL \
        --override-name auth.service_role_key=SUPABASE_SERVICE_ROLE_KEY \
        >> .env.test
  - run: bun test

Develop

After you've cloned the repository to your local machine or codespace, you'll need to perform a few setup steps before you can work on the action.

Note

You'll need a recent version of Bun for local development. This repository includes a .bun-version file for tools that can auto-switch Bun versions.

1. 🛠️ Install the dependencies

   bun install

2. ✅ Run the tests

   bun test

3. 🔍 Run the full local CI suite

   bun run ci

Publish

1. Create a new GitHub release tagged v3.X.Y, targeting the commit on main you want to publish:

   gh release create v3.X.Y --target <merge-commit-sha> --title v3.X.Y --notes "..."

2. Wait for the tag's E2E workflow run to pass

3. Move the v3 major-version tag to that same commit:

   git fetch --force origin main --tags
   git tag -f v3 <merge-commit-sha>
   git push --force origin refs/tags/v3

Your action is now published! 🚀

Note

v3 is a moving tag, not a branch — it always points at the latest v3.x.y release, per the versioning documentation. v1 and v2 predate this convention and remain real branches.

Validate

Validate changes by exercising the action from a workflow in this repository (see ci.yml and e2e.yml).

steps:
  - uses: ./
    with:
      version: latest

The CI workflow provides fast smoke coverage across GitHub-hosted runners, and the E2E workflow verifies supabase init and supabase start against supported Postgres versions. See the actions tab for recent runs.