feat(deploy): propose release version for deployments

New propose_release: --release flag > FAABLE_RELEASE env > latest git tag
(strip v, semver-shaped only), else omit. Sent as the deployment's release so
the platform injects it as FAABLE_RELEASE. Mirrors Sentry's propose-version;
no SHA fallback (the commit already travels as github_commit).

Author: boyander

src/api/FaableApi.ts

@@ -207,6 +207,7 @@ export class FaableApi<T = any> {
       manifest: { path: string; sha: string; size: number; mode?: number }[];
       plan?: unknown;
     };
+    release?: string;
     github_commit?: string;
     github_ref?: string;
     github_actor?: string;

src/commands/deploy/index.ts

@@ -4,6 +4,7 @@ import { Configuration } from '../../lib/Configuration'
 import { log } from '../../log'
 import { link } from '../link'
 import { git_context } from './git_context'
+import { propose_release } from './release_version'
 import { deploy_remote } from './remote'
 import { resolve_app_id } from './resolve_app_id'
 import { secrets } from './secrets'
@@ -12,6 +13,7 @@ import { is_superseded } from './superseded'
 export interface DeployCommandArgs {
   app_id: string
   workdir?: string
+  release?: string
 }
 
 export const deploy: CommandModule<unknown, DeployCommandArgs> = {
@@ -32,6 +34,11 @@ export const deploy: CommandModule<unknown, DeployCommandArgs> = {
         type: 'string',
         description: 'Working directory'
       })
+      .option('release', {
+        type: 'string',
+        description:
+          'Release version to record on the deployment (injected as FAABLE_RELEASE). Defaults to FAABLE_RELEASE env or the latest git tag'
+      })
       .showHelpOnFail(false) as any
   },
 
@@ -60,14 +67,28 @@ export const deploy: CommandModule<unknown, DeployCommandArgs> = {
     // it came from and who pushed it (env in CI, git fallback locally).
     const git = await git_context({ workdir })
 
+    // Propose the release version (--release > FAABLE_RELEASE > git tag).
+    // Optional: when absent the platform injects no FAABLE_RELEASE and the
+    // app falls back to its own version source.
+    const proposed = await propose_release({ workdir, explicit: args.release })
+    if (proposed) {
+      log.info(`🏷️ Release: ${proposed.release} (from ${proposed.source})`)
+    }
+
     // Remote build only (arch/deploy/remote-artifact-default-cutover.md): the
     // CLI no longer builds — it uploads the source and the platform builds
     // server-side (framework detection, buildpacks, artifact/image output all
     // live in the builder). No Docker, no local fallback: a rejected admission
     // (build_mode=local opt-out, or the global kill-switch off) or a build
     // error throws and exits red.
     log.info(`🚀 Deploying "${app.name}" (${app.id})`)
-    const deployment = await deploy_remote({ api, app, git, workdir })
+    const deployment = await deploy_remote({
+      api,
+      app,
+      git,
+      release: proposed?.release,
+      workdir
+    })
 
     const dashboard_url = `https://dashboard.faable.com/deploy/${app.team}/app/${app.id}`
     log.info(`Preparing to deploy in faable cloud · ${deployment.id}`)

src/commands/deploy/release_version.test.ts

@@ -0,0 +1,55 @@
+import test from "ava";
+import { propose_release } from "./release_version";
+
+test("explicit --release wins and is never validated", async (t) => {
+  const got = await propose_release({
+    explicit: "banana-phone",
+    env: { FAABLE_RELEASE: "9.9.9" },
+    run: async () => {
+      throw new Error("git should not be consulted with an explicit release");
+    },
+  });
+  t.deepEqual(got, { release: "banana-phone", source: "--release" });
+});
+
+test("FAABLE_RELEASE env wins over git", async (t) => {
+  const got = await propose_release({
+    env: { FAABLE_RELEASE: "2.0.0-rc.1" },
+    run: async () => {
+      throw new Error("git should not be consulted when the env var is set");
+    },
+  });
+  t.deepEqual(got, { release: "2.0.0-rc.1", source: "FAABLE_RELEASE env" });
+});
+
+test("falls back to the latest v-prefixed git tag, stripped", async (t) => {
+  const got = await propose_release({
+    env: {},
+    run: async (command) =>
+      command.includes('--match "v[0-9]*"') ? "v1.31.0" : undefined,
+  });
+  t.deepEqual(got, { release: "1.31.0", source: "git tag v1.31.0" });
+});
+
+test("retries without --match for unprefixed release tags", async (t) => {
+  const got = await propose_release({
+    env: {},
+    run: async (command) =>
+      command.includes("--match") ? undefined : "3.2.1",
+  });
+  t.deepEqual(got, { release: "3.2.1", source: "git tag 3.2.1" });
+});
+
+test("non-version tags are rejected → undefined", async (t) => {
+  const got = await propose_release({
+    env: {},
+    run: async (command) =>
+      command.includes("--match") ? undefined : "nightly",
+  });
+  t.is(got, undefined);
+});
+
+test("no git repo / no tags → undefined (deploy proceeds without release)", async (t) => {
+  const got = await propose_release({ env: {}, run: async () => undefined });
+  t.is(got, undefined);
+});

src/commands/deploy/release_version.ts

@@ -0,0 +1,63 @@
+import { exec } from "child_process";
+
+type Runner = (command: string) => Promise<string | undefined>;
+
+// Quiet git runner, same contract as git_context's: trimmed stdout or
+// undefined on any failure. A deploy must never fail because a release
+// version couldn't be proposed.
+const gitRunner =
+  (workdir?: string): Runner =>
+  command =>
+    new Promise(resolve => {
+      exec(command, { cwd: workdir }, (err, stdout) => {
+        if (err) return resolve(undefined);
+        const out = stdout?.toString().trim();
+        resolve(out || undefined);
+      });
+    });
+
+// Loose version shape: "starts like semver". Filters out non-version tags
+// (e.g. "nightly", "deploy-2026-07-01") when falling back to git describe;
+// explicit values (--release / FAABLE_RELEASE) are NEVER validated — the
+// platform treats release as free text.
+const looksLikeVersion = (v: string) => /^\d+\.\d+\.\d+/.test(v);
+
+const stripV = (tag: string) => tag.replace(/^v/, "");
+
+/**
+ * Propose the release version for a deploy (Sentry propose-version pattern):
+ * explicit `--release` > `FAABLE_RELEASE` env > latest reachable git tag
+ * (`v1.2.3` or `1.2.3`, e.g. the tag semantic-release created) > undefined.
+ * When undefined the field is omitted from the deployment and the platform
+ * injects no FAABLE_RELEASE — the app falls back to its own version source.
+ * No SHA fallback: the commit already travels as `github_commit`.
+ */
+export const propose_release = async (opts?: {
+  workdir?: string;
+  explicit?: string;
+  env?: Record<string, string | undefined>;
+  run?: Runner;
+}): Promise<{ release: string; source: string } | undefined> => {
+  const env = opts?.env ?? process.env;
+  const run = opts?.run ?? gitRunner(opts?.workdir);
+
+  if (opts?.explicit) return { release: opts.explicit, source: "--release" };
+  if (env.FAABLE_RELEASE)
+    return { release: env.FAABLE_RELEASE, source: "FAABLE_RELEASE env" };
+
+  // Latest tag reachable from HEAD. Try version-shaped tags first so a
+  // repo that also tags non-releases still resolves; retry unfiltered for
+  // repos whose release tags carry no `v` prefix.
+  for (const cmd of [
+    `git describe --tags --abbrev=0 --match "v[0-9]*"`,
+    `git describe --tags --abbrev=0`,
+  ]) {
+    const tag = await run(cmd);
+    if (!tag) continue;
+    const version = stripV(tag);
+    if (looksLikeVersion(version)) {
+      return { release: version, source: `git tag ${tag}` };
+    }
+  }
+  return undefined;
+};

src/commands/deploy/remote/index.ts

@@ -9,6 +9,8 @@ export interface DeployRemoteProps {
   api: FaableApi;
   app: FaableApp;
   git: Awaited<ReturnType<typeof git_context>>;
+  /** Proposed release version (see release_version.ts); omitted when unknown. */
+  release?: string;
   workdir: string;
 }
 
@@ -26,7 +28,7 @@ export interface DeployRemoteProps {
 export const deploy_remote = async (
   props: DeployRemoteProps
 ): Promise<{ id: string }> => {
-  const { api, app, git, workdir } = props;
+  const { api, app, git, release, workdir } = props;
 
   log.info(`☁️ Remote build`);
 
@@ -39,6 +41,7 @@ export const deploy_remote = async (
   const deployment = await api.createDeployment({
     app_id: app.id,
     source: { manifest },
+    ...(release ? { release } : {}),
     ...git,
   });