mirror of
https://github.com/supabase/setup-cli.git
synced 2026-09-27 13:17:04 +00:00
adc7f6c42c
## Summary - The Publish section still said to "Rebase \`v3\` branch on \`main\`", but \`v3\` is a moving tag, not a branch — that instruction has been stale since the v3.0.0 release moved the action to the tag-based versioning convention. - Documents the actual publish flow: create a \`vX.Y.Z\` release, wait for its E2E run to pass, then move the \`v3\` tag with \`git tag -f\` + \`git push --force\`. - Adds a note that \`v1\`/\`v2\` predate this convention and remain real branches, so contributors aren't confused by the difference. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
217 lines
6.4 KiB
Markdown
217 lines
6.4 KiB
Markdown
# :gear: Supabase CLI Action
|
|
|
|
[](https://github.com/supabase/setup-cli/actions/workflows/ci.yml)
|
|
[](https://github.com/supabase/setup-cli/actions/workflows/e2e.yml)
|
|
[](https://github.com/supabase/setup-cli/actions/workflows/codeql-analysis.yml)
|
|
|
|
## About
|
|
|
|
This composite action sets up the Supabase CLI,
|
|
[`supabase`](https://github.com/supabase/cli), on GitHub's hosted Actions
|
|
runners. Other CI runners like
|
|
[Bitbucket](https://bitbucket.org/supabase-cli/setup-cli/src/master/bitbucket-pipelines.yml)
|
|
and
|
|
[GitLab](https://gitlab.com/sweatybridge/setup-cli/-/blob/main/.gitlab-ci.yml)
|
|
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:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```dockerfile
|
|
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:
|
|
|
|
```yaml
|
|
steps:
|
|
- uses: supabase/setup-cli@v3
|
|
with:
|
|
version: 2.84.2
|
|
```
|
|
|
|
```yaml
|
|
steps:
|
|
- uses: supabase/setup-cli@v3
|
|
with:
|
|
version: beta
|
|
```
|
|
|
|
Run `supabase db start` to execute all migrations on a fresh database:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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](https://bun.sh) for local development.
|
|
> This repository includes a `.bun-version` file for tools that can auto-switch
|
|
> Bun versions.
|
|
|
|
1. :hammer_and_wrench: Install the dependencies
|
|
|
|
```bash
|
|
bun install
|
|
```
|
|
|
|
1. :white_check_mark: Run the tests
|
|
|
|
```bash
|
|
bun test
|
|
```
|
|
|
|
1. :mag: Run the full local CI suite
|
|
|
|
```bash
|
|
bun run ci
|
|
```
|
|
|
|
## Publish
|
|
|
|
1. Create a new GitHub release tagged `v3.X.Y`, targeting the commit on `main`
|
|
you want to publish:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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! :rocket:
|
|
|
|
> [!NOTE]
|
|
>
|
|
> `v3` is a moving tag, not a branch — it always points at the latest
|
|
> `v3.x.y` release, per the
|
|
> [versioning documentation](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md).
|
|
> `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](.github/workflows/ci.yml) and [e2e.yml](.github/workflows/e2e.yml)).
|
|
|
|
```yaml
|
|
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](https://github.com/supabase/setup-cli/actions)
|
|
for recent runs.
|