Mirror von supabase/setup-cli (fuer Forgejo Actions)
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Julien Goux 9f97a8880a
ci: authenticate the Dependabot app token with its client ID (#464)
The `app-id` input of `actions/create-github-app-token` is deprecated
and logs a warning on every Dependabot run. This switches
`dependabot.yml` to `client-id`, read from the new `GH_APP_CLIENT_ID`
repository variable (the public client ID of `supabase-cli-releaser`,
the same app and value `supabase/slim-services` uses).

The private key secret is unchanged. Once this merges, the `APP_ID`
repository secret has no remaining readers and can be deleted.

The workflow only runs on Dependabot PRs, so the next Dependabot PR will
exercise it.
2026-11-03 14:01:58 +00:00
.github ci: authenticate the Dependabot app token with its client ID (#464) 2026-11-03 14:01:58 +00:00
.licenses/npm Install Supabase CLI from npm (#442) 2026-07-03 12:02:44 +00:00
docs feat: fall back to the GitHub release when npm cannot install the CLI (#457) 2026-10-30 14:54:13 +00:00
src feat: resolve semver ranges in the version input (#459) 2026-11-02 13:04:13 +00:00
.bun-version chore: prepare for v2.0.0 (#405) 2026-04-03 17:51:37 +02:00
.gitignore chore: prepare for v2.0.0 (#405) 2026-04-03 17:51:37 +02:00
.licensed.yml chore: prepare for v2.0.0 (#405) 2026-04-03 17:51:37 +02:00
action.yml feat: resolve semver ranges in the version input (#459) 2026-11-02 13:04:13 +00:00
bun.lock chore(deps-dev): bump the bun-minor-patch group across 1 directory with 4 updates (#462) 2026-11-03 12:26:51 +00:00
LICENSE Initial commit 2022-08-03 21:32:01 +08:00
package.json chore(deps-dev): bump the bun-minor-patch group across 1 directory with 4 updates (#462) 2026-11-03 12:26:51 +00:00
README.md docs: document the experimental local stack for faster CI (#461) 2026-11-02 15:42:54 +01:00
tsconfig.json chore: prepare for v2.0.0 (#405) 2026-04-03 17:51:37 +02:00

⚙️ Supabase CLI Action

CI E2E CodeQL

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.

Upgrading from v1 or v2

supabase/setup-cli@v1 and @v2 are legacy and only receive compatibility fixes. New features, such as semver ranges in version, are only available in @v3. Upgrading the action does not force a CLI upgrade: @v3 installs any published CLI version, so you can keep an older CLI with an exact version or a range like ^1 or ^2:

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

@v3 installs the CLI from npm, so runners need Node.js 20+ (provisioned automatically when missing) and access to the npm registry. @v1 defaulted to CLI 2.20.3; @v3 defaults to the version in your root lockfile, or latest when there is none, so set version explicitly to keep a specific CLI.

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.

If npm cannot install a working CLI for a resolved version, for example while a fresh release is still propagating through npm, the action logs a warning and installs the same version from its GitHub release instead, after verifying the download against the release's checksums. This needs a fixed version, either requested or resolved by npm, and is skipped when the lockfile integrity check fails.

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, beta, next (upcoming major prereleases), v<N>.stable (maintenance line of an older major, like v2.stable), or an npm semver range (like ^2.95, ~2.98.0, 2.x, >=2.98 <2.99, or ^1 || ^2) of the supabase CLI can be installed. A range installs the version npm picks: latest if it matches, otherwise the highest non-deprecated match. next only tracks prereleases, so once a major goes GA it can lag behind latest until the following major's prereleases start:

steps:
  - uses: supabase/setup-cli@v3
    with:
      version: 2.84.2
steps:
  - uses: supabase/setup-cli@v3
    with:
      version: beta
steps:
  - uses: supabase/setup-cli@v3
    with:
      version: v2.stable
steps:
  - uses: supabase/setup-cli@v3
    with:
      version: ^2.95

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, next, v<N>.stable, fixed npm version, or semver range Root lockfile version or latest false

Outputs

Name Description
version Version reported by the installed supabase --version
install-source npm, or github-release when the action fell back to GitHub

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

Faster local stack (experimental)

Supabase CLI v3 includes an experimental local stack that starts much faster than the default one. On ubuntu-latest, it answers API requests about 20s after supabase start, compared to about 85s for the default stack (benchmark).

Enable it in supabase/config.toml:

[experimental]
stack = true

Without a config.toml, set SUPABASE_EXPERIMENTAL_STACK=1 for the job instead. supabase init is not needed: supabase start runs the stack with default settings.

Then start it and export its env vars for your tests:

steps:
  - uses: actions/checkout@v6
  - uses: supabase/setup-cli@v3
    with:
      version: ^3
  - run: supabase start
  - name: Export local Supabase env vars
    run: |
      supabase status --env \
        --override-name API_URL=SUPABASE_URL \
        --override-name SERVICE_ROLE_KEY=SUPABASE_SERVICE_ROLE_KEY \
        >> .env.test
  - run: bun test
  • supabase start runs the stack on Docker when it is available. On runners without Docker, such as macos-latest, use supabase start --runtime native (see the native runtime requirements).
  • Ports that config.toml doesn't set are picked per project, so read URLs and keys from supabase status --env instead of hard-coding 127.0.0.1:54321. Ports a config sets explicitly, like those written by supabase init before the stack was enabled, are used as is, and supabase start fails if one is taken. Remove them to let the stack pick free ports.
  • With a config.toml, commit the supabase/supabase.lock that supabase start writes. It pins the services the stack downloads, and when CI is set, supabase start fails instead of updating an out-of-date lock.
  • supabase start rejects some settings the stack does not support yet, such as api.tls or a db.major_version other than 15 or 17.
  • Services other than Postgres start on their first request.
  • Caching the downloaded services between runs is not needed: restoring them from the Actions cache takes about as long as downloading them.

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.