setup-cli/README.md

⚙️ 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@v2

If version is omitted, the action checks the repository root for bun.lock, pnpm-lock.yaml, or package-lock.json and uses the declared supabase version. If no supported lockfile is present, it falls back to latest.

A specific version of the supabase CLI can be installed:

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

Cache Docker images used by supabase start across workflow runs:

steps:
  - uses: actions/checkout@v6
  - uses: supabase/setup-cli@v2
    with:
      version: 2.84.2
      cache: true
  - run: supabase start

The first run still pulls images from the registry. Later runs can restore the same image set from the GitHub Actions cache before supabase start runs, and the action saves newly pulled Supabase images at the end of a successful job.

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

steps:
  - uses: supabase/setup-cli@v2
    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 version (or latest)	Root lockfile version or latest	false
cache	Boolean	Cache Docker images used by Supabase local development	false	false
cache-key	String	Explicit cache key for Supabase Docker images	Generated from runner and config	false

The action exposes these outputs:

Name	Description
version	Version of installed Supabase CLI
cache-hit	Whether an exact Supabase Docker image cache was found

Advanced Usage

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

steps:
  - uses: supabase/setup-cli@v2
  - 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@v2
  - run: supabase link --project-ref $PROJECT_ID
  - run: supabase db push

Export local Supabase env vars for app tests:

steps:
  - uses: supabase/setup-cli@v2
    with:
      cache: true
  - 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

Customize the Docker image cache key when the image set depends on your workflow flags, generated config, or monorepo layout:

steps:
  - uses: actions/checkout@v6
  - uses: supabase/setup-cli@v2
    with:
      cache: true
      cache-key: supabase-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('supabase/config.toml') }}-start-all
  - run: supabase start

Avoid running docker system prune -a before the job ends if you want the post-action cache save to include images pulled by supabase start.

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. 📦 Build the bundled action entrypoints

   bun run build
   

4. 🔍 Run the full local CI suite

   bun run ci
   

Publish

1. Create a new GitHub release
2. Rebase v2 branch on main

Your action is now published! 🚀

See the versioning documentation

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.