docs: document the v3 tag publish flow (#455)

## 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>

.github/workflows/licensed.yml

@@ -71,7 +71,7 @@ jobs:
       - name: Setup Ruby
         id: setup-ruby
         if: steps.license-inputs.outputs.changed == 'true'
-        uses: ruby/setup-ruby@6e5d382445ae5590b7449d8b3bc8cb1c2c27f617 # v1.317.0
+        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
         with:
           ruby-version: ruby
 
@@ -116,7 +116,7 @@ jobs:
 
       - name: Setup Ruby
         id: setup-ruby
-        uses: ruby/setup-ruby@6e5d382445ae5590b7449d8b3bc8cb1c2c27f617 # v1.317.0
+        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
         with:
           ruby-version: ruby
 

README.md

@@ -173,13 +173,30 @@ need to perform a few setup steps before you can work on the action.
 
 ## Publish
 
-1. Create a new GitHub release
-2. Rebase `v3` branch on `main`
+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:
 
-See the
-[versioning documentation](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
+> [!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
 

bun.lock

@@ -10,7 +10,7 @@
       "devDependencies": {
         "@tsconfig/bun": "^1.0.10",
         "@types/bun": "^1.3.14",
-        "@typescript/native-preview": "^7.0.0-dev.20260707.2",
+        "@typescript/native-preview": "^7.0.0-dev.20260410.1",
         "oxfmt": "^0.58.0",
         "oxlint": "^1.73.0",
         "oxlint-tsgolint": "^0.24.0",
@@ -120,21 +120,21 @@
 
     "@types/node": ["@types/node@20.19.37", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-8kzdPJ3FsNsVIurqBs7oodNnCEVbni9yUEkaHbgptDACOPW04jimGagZ51E6+lXUwJjgnBw+hyko/lkFWCldqw=="],
 
-    "@typescript/native-preview": ["@typescript/native-preview@7.0.0-dev.20260707.2", "", { "optionalDependencies": { "@typescript/native-preview-darwin-arm64": "7.0.0-dev.20260707.2", "@typescript/native-preview-darwin-x64": "7.0.0-dev.20260707.2", "@typescript/native-preview-linux-arm": "7.0.0-dev.20260707.2", "@typescript/native-preview-linux-arm64": "7.0.0-dev.20260707.2", "@typescript/native-preview-linux-x64": "7.0.0-dev.20260707.2", "@typescript/native-preview-win32-arm64": "7.0.0-dev.20260707.2", "@typescript/native-preview-win32-x64": "7.0.0-dev.20260707.2" }, "bin": { "tsgo": "bin/tsgo" } }, "sha512-oUGp+Rep/hqMhPunyinsALUwSlzHINSxitifPiSaeqoKOKD2OlR9NE3TaPqwsl4NlGslsOSUXI1JotWQzpYCPg=="],
+    "@typescript/native-preview": ["@typescript/native-preview@7.0.0-dev.20260410.1", "", { "optionalDependencies": { "@typescript/native-preview-darwin-arm64": "7.0.0-dev.20260410.1", "@typescript/native-preview-darwin-x64": "7.0.0-dev.20260410.1", "@typescript/native-preview-linux-arm": "7.0.0-dev.20260410.1", "@typescript/native-preview-linux-arm64": "7.0.0-dev.20260410.1", "@typescript/native-preview-linux-x64": "7.0.0-dev.20260410.1", "@typescript/native-preview-win32-arm64": "7.0.0-dev.20260410.1", "@typescript/native-preview-win32-x64": "7.0.0-dev.20260410.1" }, "bin": { "tsgo": "bin/tsgo.js" } }, "sha512-K3TIwBw4XGQM33wW8KUqRU7r6ZY1IqB8chk1u1kT+CDj4iu+eQ6jCXgU7EDxmpJ++gbNcIf8iBYgWgYNssrhZQ=="],
 
-    "@typescript/native-preview-darwin-arm64": ["@typescript/native-preview-darwin-arm64@7.0.0-dev.20260707.2", "", { "os": "darwin", "cpu": "arm64" }, "sha512-wny2pgKjGbiZtnOIHVa3tXC1UfDqxNEFzyPGmiqybedG8hipG2Nfp0l5UxbaKCjkLacUpH/W5bP2hBOMVhCOzg=="],
+    "@typescript/native-preview-darwin-arm64": ["@typescript/native-preview-darwin-arm64@7.0.0-dev.20260410.1", "", { "os": "darwin", "cpu": "arm64" }, "sha512-bpLYm6woXd8BECzV9AQvPqISVeohpekK1qwpRopvNIxydhRQ4fEjZsS7EtDYpqHAW4/u1uEv07P9/iS6TAL1fQ=="],
 
-    "@typescript/native-preview-darwin-x64": ["@typescript/native-preview-darwin-x64@7.0.0-dev.20260707.2", "", { "os": "darwin", "cpu": "x64" }, "sha512-Afc7M5zOwo+GpfcYwz5Z8HMB2tPVsui7nNIqEuuFB73MPdVqNn/Wmpe4tP4MRri0AtJnJknoHBaTJ/VDAp/Jhw=="],
+    "@typescript/native-preview-darwin-x64": ["@typescript/native-preview-darwin-x64@7.0.0-dev.20260410.1", "", { "os": "darwin", "cpu": "x64" }, "sha512-V8bW8g5hgu+bAwGvTqF1kilkkoDgxhxi5egrdMUeWQkR+MIisoBQeaAupqMpLoSkqZsc/kKucM0zwBNC/KRU3Q=="],
 
-    "@typescript/native-preview-linux-arm": ["@typescript/native-preview-linux-arm@7.0.0-dev.20260707.2", "", { "os": "linux", "cpu": "arm" }, "sha512-hJm/UOqZTr9FHmR7uNm8VGX4oKtfWk0Jem0zPeJFNC8ckGUfSBueyiEYMZB+XmRc1aG4x1E46y3CplP4CLHvGQ=="],
+    "@typescript/native-preview-linux-arm": ["@typescript/native-preview-linux-arm@7.0.0-dev.20260410.1", "", { "os": "linux", "cpu": "arm" }, "sha512-NO6Ci65ADadOCr2ycTxOyCgC5kyk+Ryjl8k5c78mz9sKDxYqwEtryFFjLqitAG+rejtJbnUq897WRICjAOwslA=="],
 
-    "@typescript/native-preview-linux-arm64": ["@typescript/native-preview-linux-arm64@7.0.0-dev.20260707.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-iITBa2WjjTI5N9t5l7Z4KoOSI+2zBlhbvFzsD/f8qX8QoKjz/Y4DPyBDgezYi8nkqjjksbgSOJ3/ykzhwrB9cg=="],
+    "@typescript/native-preview-linux-arm64": ["@typescript/native-preview-linux-arm64@7.0.0-dev.20260410.1", "", { "os": "linux", "cpu": "arm64" }, "sha512-MOluRRAhv46s9ScFmePa0InMHmpZ/z0Evc11RrTKsg+bN8BR7sWoAtFq6IujEDK9WVP7YmEYtBRgEfMLuqVojw=="],
 
-    "@typescript/native-preview-linux-x64": ["@typescript/native-preview-linux-x64@7.0.0-dev.20260707.2", "", { "os": "linux", "cpu": "x64" }, "sha512-du0dzi6y97Po5vDNdPJTyyijHCpaS22JLRnKZEJXBDaO9gCIymOv/5QQokFRuOlQm0bWl3i9PF4OVdGP6uAOQA=="],
+    "@typescript/native-preview-linux-x64": ["@typescript/native-preview-linux-x64@7.0.0-dev.20260410.1", "", { "os": "linux", "cpu": "x64" }, "sha512-IofIUrMGjXmZKDEMaRgshzOne0EQZtx9vE/6URHfgmDnWLDKWzz9eQ2qWmvsFD2vOBbgc6GwVWEq6XTHMEfx2A=="],
 
-    "@typescript/native-preview-win32-arm64": ["@typescript/native-preview-win32-arm64@7.0.0-dev.20260707.2", "", { "os": "win32", "cpu": "arm64" }, "sha512-SsAwfhyHJ1akgBc+99z4+hwdbHsdWaKB8EwCNIMA6JfSLMeUjffrYvxu+vfMyxVtOVOz7RrRXRoiDiu4a2sCtg=="],
+    "@typescript/native-preview-win32-arm64": ["@typescript/native-preview-win32-arm64@7.0.0-dev.20260410.1", "", { "os": "win32", "cpu": "arm64" }, "sha512-TXmE+wovQqRo+qAhaewB0MPB9esgayvSHr6vFlCpHykHqbDl3FUucuC4F8yU6zVOA3UqXTk4/GHeLsAvU7YEgQ=="],
 
-    "@typescript/native-preview-win32-x64": ["@typescript/native-preview-win32-x64@7.0.0-dev.20260707.2", "", { "os": "win32", "cpu": "x64" }, "sha512-DL4u27stv0fo71sVhOzHSwE+YMZsbBijVI+kg5dLDLilSH79WFTJ8RSQ46vJrCMt+Gjlv/JOZP1PuLJDfioYeQ=="],
+    "@typescript/native-preview-win32-x64": ["@typescript/native-preview-win32-x64@7.0.0-dev.20260410.1", "", { "os": "win32", "cpu": "x64" }, "sha512-dMFT4tdHBe2vVA2WPQMjorT+fzCURRtillevQzz8/bwCEz2uXSnpu4oLRLS5045ppGE0wCFELE+Hq5z2oRddDw=="],
 
     "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
 

package.json

@@ -29,7 +29,7 @@
   "devDependencies": {
     "@tsconfig/bun": "^1.0.10",
     "@types/bun": "^1.3.14",
-    "@typescript/native-preview": "^7.0.0-dev.20260707.2",
+    "@typescript/native-preview": "^7.0.0-dev.20260410.1",
     "oxfmt": "^0.58.0",
     "oxlint": "^1.73.0",
     "oxlint-tsgolint": "^0.24.0"

src/main.test.ts

@@ -10,6 +10,7 @@ const originalPath = process.env.PATH;
 const originalNpmUserconfig = process.env.NPM_CONFIG_USERCONFIG;
 const originalRunnerTemp = process.env.RUNNER_TEMP;
 const originalWorkspace = process.env.GITHUB_WORKSPACE;
+const originalImageRegistry = process.env.SUPABASE_INTERNAL_IMAGE_REGISTRY;
 const tempDirs = new Set<string>();
 let mainModule: typeof import("./main.ts") | null = null;
 
@@ -21,8 +22,21 @@ afterEach(() => {
   } else {
     process.env.NPM_CONFIG_USERCONFIG = originalNpmUserconfig;
   }
-  process.env.RUNNER_TEMP = originalRunnerTemp;
-  process.env.GITHUB_WORKSPACE = originalWorkspace;
+  if (originalRunnerTemp === undefined) {
+    delete process.env.RUNNER_TEMP;
+  } else {
+    process.env.RUNNER_TEMP = originalRunnerTemp;
+  }
+  if (originalWorkspace === undefined) {
+    delete process.env.GITHUB_WORKSPACE;
+  } else {
+    process.env.GITHUB_WORKSPACE = originalWorkspace;
+  }
+  if (originalImageRegistry === undefined) {
+    delete process.env.SUPABASE_INTERNAL_IMAGE_REGISTRY;
+  } else {
+    process.env.SUPABASE_INTERNAL_IMAGE_REGISTRY = originalImageRegistry;
+  }
   delete process.env.FAKE_CLI_VERSION;
   delete process.env.FAKE_NPM_BIN;
   delete process.env.FAKE_NPM_INTEGRITY;
@@ -743,6 +757,41 @@ test("explicit version overrides detected root lockfiles", async () => {
   expect(spies.setFailed).not.toHaveBeenCalled();
 });
 
+test("pins legacy installed CLI versions to GHCR", async () => {
+  installFakeNpm("supabase 2.107.0");
+  const spies = createActionSpies("2.107.0");
+  const { run } = await getMainModule();
+
+  await run();
+
+  expect(spies.exportVariable).toHaveBeenCalledWith(CLI_CONFIG_REGISTRY, "ghcr.io");
+  expect(spies.setFailed).not.toHaveBeenCalled();
+});
+
+test("uses the CLI registry fallback for installed versions that support it", async () => {
+  installFakeNpm("supabase 2.108.0");
+  const spies = createActionSpies("latest");
+  const { run } = await getMainModule();
+
+  await run();
+
+  expect(spies.exportVariable).not.toHaveBeenCalled();
+  expect(spies.setFailed).not.toHaveBeenCalled();
+});
+
+test("preserves an explicitly configured image registry for legacy CLI versions", async () => {
+  installFakeNpm("supabase 2.107.0");
+  process.env.SUPABASE_INTERNAL_IMAGE_REGISTRY = "registry.example.test";
+  const spies = createActionSpies("2.107.0");
+  const { run } = await getMainModule();
+
+  await run();
+
+  expect(spies.exportVariable).not.toHaveBeenCalled();
+  expect(process.env.SUPABASE_INTERNAL_IMAGE_REGISTRY).toBe("registry.example.test");
+  expect(spies.setFailed).not.toHaveBeenCalled();
+});
+
 test("fails when the installed CLI does not report a version", async () => {
   installFakeNpm("");
   process.env.GITHUB_WORKSPACE = createWorkspace({

src/main.ts

@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";
 
 export const CLI_CONFIG_REGISTRY = "SUPABASE_INTERNAL_IMAGE_REGISTRY";
 const REGISTRY_VERSION = "1.28.0";
+const FALLBACK_VERSION = "2.108.0";
 const DEFAULT_VERSION = "latest";
 const NPM_PACKAGE = "supabase";
 const NPM_EXECUTABLE_ENV = "SUPABASE_SETUP_CLI_NPM";
@@ -379,13 +380,13 @@ export async function determineInstalledVersion(cliPath: string): Promise<string
   return version;
 }
 
-function shouldUseGhcrRegistry(requestedVersion: string, installedVersion: string): boolean {
-  if (requestedVersion.toLowerCase() === DEFAULT_VERSION) {
-    return true;
-  }
-
+function shouldUseGhcrRegistry(installedVersion: string): boolean {
   const concreteVersion = extractConcreteVersion(installedVersion);
-  return concreteVersion !== null && semver.order(concreteVersion, REGISTRY_VERSION) >= 0;
+  return (
+    concreteVersion !== null &&
+    semver.order(concreteVersion, REGISTRY_VERSION) >= 0 &&
+    semver.order(concreteVersion, FALLBACK_VERSION) < 0
+  );
 }
 
 export async function run(): Promise<void> {
@@ -396,7 +397,7 @@ export async function run(): Promise<void> {
     core.setOutput("version", installedVersion);
     core.addPath(cliPath);
 
-    if (shouldUseGhcrRegistry(resolution.version, installedVersion)) {
+    if (shouldUseGhcrRegistry(installedVersion) && !process.env[CLI_CONFIG_REGISTRY]) {
       core.exportVariable(CLI_CONFIG_REGISTRY, "ghcr.io");
     }
   } catch (error) {