@liiift-studio/deploy-vercel-from-sanity 1.3.2 → 1.4.0

package/README.md

@@ -149,6 +149,7 @@ A target needs **either** `url` **or** `proxyKey`; the schema enforces that.
 | `mode` | `'direct' \| 'proxy'` | `'direct'` | Transport used to reach Vercel — see [Two modes](#two-modes) |
 | `proxyUrl` | `string` | — | Base URL of the deploy proxy, no trailing slash. Required when `mode` is `'proxy'`. |
 | `statusKey` | `string` | — | Key sent with status requests. Must match the proxy's `VERCEL_DEPLOY_STATUS_KEY`. Ships in the Studio bundle — treat it as public. |
+| `unblock` | `UnblockConfig` | — | Enables recovery from author-blocked deploys — see [Recovering a blocked deploy](#recovering-a-blocked-deploy). Omit to leave the feature off. |
 
 ---
 
@@ -274,6 +275,137 @@ can cancel a running build for the configured targets — see
 
 ---
 
+## Recovering a blocked deploy
+
+Vercel will not build a commit whose **git author is not a member of the team
+that owns the project**. It creates the deployment, marks it `BLOCKED`, and
+compiles nothing. There is no build log, because there was no build.
+
+This is easy to miss. The deployment appears in the history like any other, and
+before 1.4.0 the state was not in the plugin's union at all, so it rendered as
+*Unknown* — an editor pressed **Deploy**, saw nothing go wrong, and waited for a
+site that was never going to update.
+
+**Pressing Deploy again cannot fix it.** The deploy hook rebuilds the current
+HEAD, which is the same commit with the same author, so it is blocked
+identically. The only way out is a new commit by an authorised author.
+
+A Studio running in a browser holds no git credential, so it cannot make that
+commit itself. With `unblock` configured it dispatches a GitHub Actions workflow
+that does.
+
+### The credential split
+
+This is the part worth understanding before enabling it.
+
+```
+Studio bundle  ──  unblock.token   Actions: write, one repo
+                        │          public — anyone who can open the Studio can read it
+                        ▼
+GitHub Actions ──  DEPLOY_COMMIT_TOKEN   Contents: write
+                        │                never leaves GitHub
+                        ▼
+              commit as an authorised author  ──▶  Vercel builds it
+```
+
+Handing the Studio a `Contents: write` token would be far simpler and is the
+obvious first design. Do not: the Studio bundle is served publicly, so that token
+would let anyone who can load the Studio push arbitrary commits to the production
+repository — and the next build would run them. The dispatch token is scoped so
+that the worst a leak permits is *running the bump workflow*, which produces a
+version bump and a deploy.
+
+### What a leaked dispatch token can actually do
+
+Be clear-eyed about this rather than filing it under "public by design":
+
+- It **cannot** read your code, read other secrets, or push commits.
+- It **can** run the bump workflow repeatedly — churning version commits and
+  burning Vercel build minutes.
+- It **can**, without the branch allowlist, bump your *production* branch and so
+  force a deploy of whatever is currently on it. No attacker code is introduced —
+  it deploys already-merged commits — but an outsider should not be able to
+  trigger a production release.
+
+The shipped workflow therefore opens with a branch allowlist, and a `concurrency`
+group that serialises bumps per branch. Narrow the allowlist to the branches you
+actually deploy. Rotate the token if it leaks.
+
+### 1. Add the workflow
+
+Copy [`docs/version-bump.yml`](docs/version-bump.yml) to
+`.github/workflows/version-bump.yml` in the **site** repository, then set the git
+identity in it to the account whose commits Vercel accepts, and narrow the branch
+allowlist to the branches you deploy.
+
+> **The workflow file must exist on the repository's default branch**, and on
+> every branch you deploy from. GitHub resolves a dispatch against the default
+> branch's copy, then runs the copy on the requested ref. A file present only on
+> `staging` returns a 404 — which the plugin reports in full, since GitHub uses
+> the same 404 for "no such workflow" and "your token cannot see this repo".
+
+### 2. Add the commit credential
+
+Create a fine-grained token on the account whose commits Vercel accepts, scoped
+to **`Contents: write`** on that one repository, and save it as the repository
+Actions secret **`DEPLOY_COMMIT_TOKEN`**.
+
+It must not be the default `GITHUB_TOKEN`: commits made with it are authored by
+`github-actions[bot]`, which is not a team member either, so Vercel would block
+the bump for the same reason it blocked the original commit.
+
+### 3. Add the dispatch token
+
+Create a second fine-grained token scoped to **`Actions: write`** on the same
+repository — and nothing else — and expose it to the Studio build:
+
+```sh
+SANITY_STUDIO_DEPLOY_UNBLOCK_GH_TOKEN=github_pat_…
+```
+
+### 4. Configure the plugin
+
+```ts
+vercelDeploy({
+  unblock: {
+    token: process.env.SANITY_STUDIO_DEPLOY_UNBLOCK_GH_TOKEN,
+    owner: 'your-org',
+    repo: 'your-site-repo',
+    workflow: 'version-bump.yml',   // optional, this is the default
+  },
+})
+```
+
+| Field | Required | Description |
+|---|---|---|
+| `token` | yes | Fine-grained token, `Actions: write` on `repo` only. Ships in the Studio bundle — treat it as public. Unset hides the button. |
+| `owner` | yes | Repository owner, e.g. `your-org` |
+| `repo` | yes | Repository name |
+| `workflow` | no | Workflow filename. Defaults to `version-bump.yml`. |
+| `defaultRef` | no | Branch to bump when the blocked deployment names none. Normally unnecessary — the branch is read from the deployment being recovered. |
+
+An `unblock` block missing `token`, `owner` or `repo` is discarded, so a
+half-finished configuration renders no button rather than one that only errors.
+
+### What the editor sees
+
+The button appears only when the latest deployment is actually `BLOCKED`. It is
+not a general "deploy harder" control, and it is deliberately not offered when
+the plugin has nothing to target.
+
+Pressing it reports that the bump was **requested**. That is the honest claim:
+GitHub has accepted the dispatch, but the workflow still has to run, commit and
+push before Vercel sees anything, so the new deployment turns up a minute or two
+later. Polling picks it up on its own.
+
+### The real fix
+
+This is a recovery lever, not a cure. If the same author is blocked repeatedly,
+add their GitHub account to the Vercel team — that removes the failure entirely.
+Keep `unblock` for the cases you cannot prevent.
+
+---
+
 ## Troubleshooting
 
 ### "Vercel API 401 — token is invalid or expired"

package/dist/index.d.mts

@@ -1,7 +1,14 @@
 import * as sanity from 'sanity';
 import * as react from 'react';
 
-type VercelDeployState = 'QUEUED' | 'INITIALIZING' | 'BUILDING' | 'READY' | 'ERROR' | 'CANCELED' | 'LOADING';
+type VercelDeployState = 'QUEUED' | 'INITIALIZING' | 'BUILDING' | 'READY' | 'ERROR' | 'CANCELED'
+/**
+ * Vercel refused to build the commit because its git author is not a member of
+ * the team that owns the project. Nothing was compiled, so there are no build
+ * logs to read — the fix is a new commit by an authorised author, not a retry.
+ * Re-firing the deploy hook cannot clear it: the hook rebuilds the same HEAD.
+ */
+ | 'BLOCKED' | 'LOADING';
 /** A vercel_deploy document stored in the Sanity dataset */
 interface DeployTarget {
     _id: string;
@@ -47,6 +54,12 @@ interface VercelDeployment {
         githubCommitRef?: string;
         githubCommitSha?: string;
         githubCommitAuthorName?: string;
+        /**
+         * GitHub login of the commit author. This — not `creator` — is what Vercel
+         * checks when deciding whether to build, so it is the value to name when a
+         * deployment comes back BLOCKED.
+         */
+        githubCommitAuthorLogin?: string;
         /** GitHub repo in "org/repo" format — used to construct commit links */
         githubRepo?: string;
         /** GitHub org slug — fallback when githubRepo is absent */
@@ -66,6 +79,50 @@ interface VercelDeployment {
  *   `proxy/README.md`.
  */
 type VercelDeployMode = 'direct' | 'proxy';
+/**
+ * Opt-in recovery path for deployments Vercel refuses to build because the HEAD
+ * commit's git author is not a member of the Vercel team.
+ *
+ * The Studio cannot fix this itself — the remedy is a commit by an authorised
+ * author, and a browser holds no git credential. So the button dispatches a
+ * GitHub Actions workflow, and that workflow does the commit with a token held
+ * in Actions secrets.
+ *
+ * The split matters. {@link token} ships inside the Studio bundle and must be
+ * treated as public; scope it to **Actions: write on the one repo** so the worst
+ * a leak permits is running that workflow. The credential that can actually
+ * write code stays in GitHub, where the browser never sees it.
+ */
+interface UnblockConfig {
+    /**
+     * Fine-grained GitHub token, scoped to `Actions: write` on {@link repo} alone.
+     *
+     * Compiled into the Studio bundle, so anyone who can load the Studio can read
+     * it and dispatch the workflow. Never give it `Contents: write` — that would
+     * let a reader push arbitrary commits to the production repo.
+     *
+     * Leave unset to hide the button entirely.
+     */
+    token?: string;
+    /** Repository owner, e.g. `Liiift-Studio`. */
+    owner: string;
+    /** Repository name, e.g. `the-designers-foundry`. */
+    repo: string;
+    /**
+     * Workflow filename to dispatch. Defaults to `version-bump.yml`.
+     *
+     * GitHub resolves a dispatch against the workflow file **on the repository's
+     * default branch**, then runs the copy on the requested ref — so the file must
+     * exist on the default branch as well as on every branch you deploy from, or
+     * the dispatch returns 404.
+     */
+    workflow?: string;
+    /**
+     * Branch to bump when the blocked deployment does not name one. Normally
+     * unnecessary: the branch is read from the deployment being unblocked.
+     */
+    defaultRef?: string;
+}
 /** Plugin configuration options */
 interface VercelDeployPluginConfig {
     /** Tool name slug shown in Studio sidebar (default: 'vercel-deploy') */
@@ -94,6 +151,12 @@ interface VercelDeployPluginConfig {
      * API token never leaves the proxy.
      */
     statusKey?: string;
+    /**
+     * Enables the "Bump version" recovery button on deployments Vercel blocked for
+     * git-author reasons. Omit to leave the feature off — the button never renders
+     * and no GitHub token is required.
+     */
+    unblock?: UnblockConfig;
 }
 
 declare const vercelDeploySchema: {
@@ -159,4 +222,4 @@ declare const vercelDeploySchema: {
  */
 declare const vercelDeploy: sanity.Plugin<void | VercelDeployPluginConfig>;
 
-export { type DeployTarget, type VercelDeployMode, type VercelDeployPluginConfig, type VercelDeployState, type VercelDeployment, vercelDeploy, vercelDeploySchema };
+export { type DeployTarget, type UnblockConfig, type VercelDeployMode, type VercelDeployPluginConfig, type VercelDeployState, type VercelDeployment, vercelDeploy, vercelDeploySchema };

package/dist/index.d.ts

@@ -1,7 +1,14 @@
 import * as sanity from 'sanity';
 import * as react from 'react';
 
-type VercelDeployState = 'QUEUED' | 'INITIALIZING' | 'BUILDING' | 'READY' | 'ERROR' | 'CANCELED' | 'LOADING';
+type VercelDeployState = 'QUEUED' | 'INITIALIZING' | 'BUILDING' | 'READY' | 'ERROR' | 'CANCELED'
+/**
+ * Vercel refused to build the commit because its git author is not a member of
+ * the team that owns the project. Nothing was compiled, so there are no build
+ * logs to read — the fix is a new commit by an authorised author, not a retry.
+ * Re-firing the deploy hook cannot clear it: the hook rebuilds the same HEAD.
+ */
+ | 'BLOCKED' | 'LOADING';
 /** A vercel_deploy document stored in the Sanity dataset */
 interface DeployTarget {
     _id: string;
@@ -47,6 +54,12 @@ interface VercelDeployment {
         githubCommitRef?: string;
         githubCommitSha?: string;
         githubCommitAuthorName?: string;
+        /**
+         * GitHub login of the commit author. This — not `creator` — is what Vercel
+         * checks when deciding whether to build, so it is the value to name when a
+         * deployment comes back BLOCKED.
+         */
+        githubCommitAuthorLogin?: string;
         /** GitHub repo in "org/repo" format — used to construct commit links */
         githubRepo?: string;
         /** GitHub org slug — fallback when githubRepo is absent */
@@ -66,6 +79,50 @@ interface VercelDeployment {
  *   `proxy/README.md`.
  */
 type VercelDeployMode = 'direct' | 'proxy';
+/**
+ * Opt-in recovery path for deployments Vercel refuses to build because the HEAD
+ * commit's git author is not a member of the Vercel team.
+ *
+ * The Studio cannot fix this itself — the remedy is a commit by an authorised
+ * author, and a browser holds no git credential. So the button dispatches a
+ * GitHub Actions workflow, and that workflow does the commit with a token held
+ * in Actions secrets.
+ *
+ * The split matters. {@link token} ships inside the Studio bundle and must be
+ * treated as public; scope it to **Actions: write on the one repo** so the worst
+ * a leak permits is running that workflow. The credential that can actually
+ * write code stays in GitHub, where the browser never sees it.
+ */
+interface UnblockConfig {
+    /**
+     * Fine-grained GitHub token, scoped to `Actions: write` on {@link repo} alone.
+     *
+     * Compiled into the Studio bundle, so anyone who can load the Studio can read
+     * it and dispatch the workflow. Never give it `Contents: write` — that would
+     * let a reader push arbitrary commits to the production repo.
+     *
+     * Leave unset to hide the button entirely.
+     */
+    token?: string;
+    /** Repository owner, e.g. `Liiift-Studio`. */
+    owner: string;
+    /** Repository name, e.g. `the-designers-foundry`. */
+    repo: string;
+    /**
+     * Workflow filename to dispatch. Defaults to `version-bump.yml`.
+     *
+     * GitHub resolves a dispatch against the workflow file **on the repository's
+     * default branch**, then runs the copy on the requested ref — so the file must
+     * exist on the default branch as well as on every branch you deploy from, or
+     * the dispatch returns 404.
+     */
+    workflow?: string;
+    /**
+     * Branch to bump when the blocked deployment does not name one. Normally
+     * unnecessary: the branch is read from the deployment being unblocked.
+     */
+    defaultRef?: string;
+}
 /** Plugin configuration options */
 interface VercelDeployPluginConfig {
     /** Tool name slug shown in Studio sidebar (default: 'vercel-deploy') */
@@ -94,6 +151,12 @@ interface VercelDeployPluginConfig {
      * API token never leaves the proxy.
      */
     statusKey?: string;
+    /**
+     * Enables the "Bump version" recovery button on deployments Vercel blocked for
+     * git-author reasons. Omit to leave the feature off — the button never renders
+     * and no GitHub token is required.
+     */
+    unblock?: UnblockConfig;
 }
 
 declare const vercelDeploySchema: {
@@ -159,4 +222,4 @@ declare const vercelDeploySchema: {
  */
 declare const vercelDeploy: sanity.Plugin<void | VercelDeployPluginConfig>;
 
-export { type DeployTarget, type VercelDeployMode, type VercelDeployPluginConfig, type VercelDeployState, type VercelDeployment, vercelDeploy, vercelDeploySchema };
+export { type DeployTarget, type UnblockConfig, type VercelDeployMode, type VercelDeployPluginConfig, type VercelDeployState, type VercelDeployment, vercelDeploy, vercelDeploySchema };

package/dist/index.js

@@ -108,7 +108,10 @@ function resolveConfig(options) {
     mode: config.mode ?? "direct",
     // Trailing slashes would double up when request paths are appended.
     proxyUrl: config.proxyUrl?.replace(/\/+$/, ""),
-    statusKey: config.statusKey
+    statusKey: config.statusKey,
+    // Dropped unless it can actually be used. A config missing the token, the owner
+    // or the repo would otherwise render a button whose only outcome is an error.
+    unblock: config.unblock?.token && config.unblock.owner && config.unblock.repo ? config.unblock : void 0
   };
 }
 function ConfigProvider({ value, children }) {
@@ -701,6 +704,62 @@ async function fetchDeploymentEvents(transport, target, deploymentId) {
   return data.events ?? [];
 }
 
+// src/lib/github.ts
+var GITHUB_API = "https://api.github.com";
+var DEFAULT_WORKFLOW = "version-bump.yml";
+var SEGMENT_RE = /^[A-Za-z0-9._-]+$/;
+var REF_RE = /^[A-Za-z0-9._\-/]+$/;
+function isValidRef(ref) {
+  if (!ref || ref.length > 255) return false;
+  if (!REF_RE.test(ref)) return false;
+  if (ref.includes("..") || ref.includes("//")) return false;
+  if (ref.startsWith("/") || ref.endsWith("/")) return false;
+  if (ref.startsWith("-") || ref.endsWith(".lock")) return false;
+  return true;
+}
+async function dispatchVersionBump(opts) {
+  const { config, ref, requestedBy } = opts;
+  const workflow = config.workflow ?? DEFAULT_WORKFLOW;
+  if (!config.token) throw new Error("No GitHub token is configured for deploy recovery.");
+  if (!SEGMENT_RE.test(config.owner)) throw new Error(`Invalid repository owner "${config.owner}".`);
+  if (!SEGMENT_RE.test(config.repo)) throw new Error(`Invalid repository name "${config.repo}".`);
+  if (!SEGMENT_RE.test(workflow)) throw new Error(`Invalid workflow filename "${workflow}".`);
+  if (!isValidRef(ref)) throw new Error(`Invalid branch name "${ref}".`);
+  const path = `/repos/${encodeURIComponent(config.owner)}/${encodeURIComponent(config.repo)}/actions/workflows/${encodeURIComponent(workflow)}/dispatches`;
+  const res = await fetch(`${GITHUB_API}${path}`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${config.token}`,
+      Accept: "application/vnd.github+json",
+      "X-GitHub-Api-Version": "2022-11-28",
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({
+      ref,
+      // Workflow inputs are strings; anything else is rejected with a 422.
+      inputs: { requested_by: (requestedBy ?? "a Studio user").slice(0, 80) }
+    })
+  });
+  if (res.status === 204) return;
+  throw new Error(`${dispatchErrorMessage(res.status, workflow, ref)} (GitHub ${res.status})`);
+}
+function dispatchErrorMessage(status, workflow, ref) {
+  switch (status) {
+    case 401:
+      return "The GitHub token is invalid or expired. Ask a developer to reissue it.";
+    case 403:
+      return "The GitHub token is not allowed to run workflows on this repository. It needs Actions: write.";
+    case 404:
+      return `GitHub could not find "${workflow}". It must exist on the repository's default branch as well as on "${ref}" \u2014 or the token cannot see this repository.`;
+    case 422:
+      return `GitHub rejected the request: branch "${ref}" may not exist, or "${workflow}" has no workflow_dispatch trigger.`;
+    case 429:
+      return "GitHub rate limit reached. Wait a minute and try again.";
+    default:
+      return status >= 500 ? "GitHub is having problems. Try again shortly." : "The version bump could not be started.";
+  }
+}
+
 // src/components/DeployItem.tsx
 var import_sanity = require("sanity");
 
@@ -769,6 +828,11 @@ function stateLabel(state) {
       return { label: "Initializing", tone: "caution" };
     case "ERROR":
       return { label: "Error", tone: "critical" };
+    // Distinct from Error: nothing was built, so there is no log to read and a
+    // retry changes nothing. Labelling it 'Unknown' is what made this failure
+    // invisible to editors, who saw a deploy that simply never arrived.
+    case "BLOCKED":
+      return { label: "Blocked", tone: "critical" };
     case "CANCELED":
       return { label: "Canceled", tone: "default" };
     case "LOADING":
@@ -916,6 +980,7 @@ function DeployItem({ target, token, onDelete, onEdit }) {
   const toast = useToast();
   const pluginConfig = usePluginConfig();
   const client = (0, import_sanity.useClient)({ apiVersion: "2025-01-01" });
+  const currentUser = (0, import_sanity.useCurrentUser)();
   const transport = (0, import_react8.useMemo)(
     () => pluginConfig.mode === "proxy" ? { mode: "proxy", proxyUrl: pluginConfig.proxyUrl ?? "", statusKey: pluginConfig.statusKey } : { mode: "direct", token },
     [pluginConfig.mode, pluginConfig.proxyUrl, pluginConfig.statusKey, token]
@@ -938,6 +1003,8 @@ function DeployItem({ target, token, onDelete, onEdit }) {
   const [loadingLogs, setLoadingLogs] = (0, import_react8.useState)(false);
   const [logError, setLogError] = (0, import_react8.useState)(null);
   const [pollError, setPollError] = (0, import_react8.useState)(null);
+  const [bumping, setBumping] = (0, import_react8.useState)(false);
+  const [bumpResult, setBumpResult] = (0, import_react8.useState)(null);
   const triggeredFromUidRef = (0, import_react8.useRef)(void 0);
   const requestSeqRef = (0, import_react8.useRef)(0);
   const mountedRef = (0, import_react8.useRef)(true);
@@ -1084,6 +1151,35 @@ function DeployItem({ target, token, onDelete, onEdit }) {
     if (!showErrorLogs && errorLines.length === 0 && !logError) fetchErrorLogs();
     setShowErrorLogs((v) => !v);
   }, [showErrorLogs, errorLines.length, logError, fetchErrorLogs]);
+  const requestBump = (0, import_react8.useCallback)(async () => {
+    const unblockConfig = pluginConfig.unblock;
+    const ref = latest?.meta?.githubCommitRef ?? unblockConfig?.defaultRef;
+    if (!unblockConfig || !ref) return;
+    setBumping(true);
+    setBumpResult(null);
+    try {
+      await dispatchVersionBump({
+        config: unblockConfig,
+        ref,
+        requestedBy: currentUser?.name || currentUser?.email || void 0
+      });
+      setBumpResult({
+        ok: true,
+        message: `Version bump requested on ${ref}. The new deploy appears here in a minute or two.`
+      });
+      toast.push({
+        status: "success",
+        title: "Version bump requested",
+        description: `${target.name} will redeploy once the bump commit lands on ${ref}.`
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "The version bump could not be started.";
+      setBumpResult({ ok: false, message });
+      toast.push({ status: "error", title: "Could not request a version bump", description: message });
+    } finally {
+      setBumping(false);
+    }
+  }, [pluginConfig.unblock, latest?.meta?.githubCommitRef, currentUser, target.name, toast]);
   const branch = latest?.meta?.githubCommitRef;
   const commitMsg = latest?.meta?.githubCommitMessage?.split("\n")[0];
   const sha = shortSha(latest?.meta?.githubCommitSha);
@@ -1093,6 +1189,10 @@ function DeployItem({ target, token, onDelete, onEdit }) {
   const deployedAt = latest?.created ? timeAgo(latest.created) : null;
   const vercelProjectUrl = projectHref(latest?.inspectorUrl);
   const isError = latest?.state === "ERROR";
+  const isBlocked = latest?.state === "BLOCKED";
+  const blockedAuthor = latest?.meta?.githubCommitAuthorLogin ?? latest?.meta?.githubCommitAuthorName;
+  const bumpRef = branch ?? pluginConfig.unblock?.defaultRef;
+  const canUnblock = Boolean(isBlocked && pluginConfig.unblock && bumpRef);
   return /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(import_jsx_runtime10.Fragment, { children: [
     /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(Card, { radius: 2, shadow: 1, tone: "default", children: /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(Flex, { align: "stretch", className: "dvfs-card-flex", children: [
       /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(Flex, { direction: "column", flex: 1, style: { minWidth: 0 }, children: [
@@ -1256,7 +1356,48 @@ function DeployItem({ target, token, onDelete, onEdit }) {
                 ] })
               ] }),
               deployError && /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(Card, { tone: "critical", padding: 2, radius: 2, children: /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(Text, { size: 1, children: deployError }) })
-            ] })
+            ] }),
+            isBlocked && /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(Card, { tone: "critical", padding: 3, radius: 2, children: /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(Stack, { space: 3, children: [
+              /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(Flex, { align: "flex-start", gap: 2, children: [
+                /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(Box, { style: { flexShrink: 0, marginTop: 2 }, children: /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(WarningOutlineIcon, { "aria-hidden": "true" }) }),
+                /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(Stack, { space: 2, children: [
+                  /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(Text, { size: 1, weight: "semibold", children: "Vercel refused to build this commit" }),
+                  /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(Text, { size: 1, children: [
+                    blockedAuthor ? /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(import_jsx_runtime10.Fragment, { children: [
+                      "The last commit was authored by ",
+                      /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("strong", { children: blockedAuthor }),
+                      ", who is not a member of the Vercel team, so the build never started."
+                    ] }) : /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(import_jsx_runtime10.Fragment, { children: "The last commit's author is not a member of the Vercel team, so the build never started." }),
+                    " ",
+                    "Deploying again will not help \u2014 it rebuilds the same commit."
+                  ] })
+                ] })
+              ] }),
+              canUnblock ? /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(Stack, { space: 2, children: [
+                /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
+                  Button,
+                  {
+                    text: bumping ? "Requesting\u2026" : "Bump version and redeploy",
+                    tone: "critical",
+                    icon: RocketIcon,
+                    fontSize: 1,
+                    loading: bumping,
+                    disabled: bumping || bumpResult?.ok === true,
+                    onClick: requestBump,
+                    style: { alignSelf: "flex-start", cursor: "pointer" }
+                  }
+                ),
+                /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(Text, { size: 0, muted: true, children: [
+                  "Adds an authorised version-bump commit on ",
+                  /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("code", { children: bumpRef }),
+                  ", which Vercel will build."
+                ] })
+              ] }) : /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(Text, { size: 0, muted: true, children: pluginConfig.unblock ? "This deployment carries no branch information, so a version bump cannot be targeted. Ask a developer to deploy manually." : "Ask a developer to push a version bump \u2014 a commit by an authorised author is needed before this site can deploy." }),
+              bumpResult && /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(Text, { size: 0, weight: bumpResult.ok ? "semibold" : void 0, children: [
+                bumpResult.ok ? "\u2713 " : "",
+                bumpResult.message
+              ] })
+            ] }) })
           ] }),
           pollError && /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(Card, { tone: "caution", padding: 3, radius: 2, children: /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(Flex, { align: "center", gap: 2, children: [
             /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(WarningOutlineIcon, { "aria-hidden": "true" }),
@@ -1644,7 +1785,7 @@ function DeployTargetForm({ initial, onSaved, onClose }) {
 }
 
 // src/version.ts
-var VERSION = "1.3.2";
+var VERSION = "1.4.0";
 
 // src/components/DeployTool.tsx
 var import_jsx_runtime13 = require("react/jsx-runtime");

package/dist/index.mjs

@@ -73,7 +73,10 @@ function resolveConfig(options) {
     mode: config.mode ?? "direct",
     // Trailing slashes would double up when request paths are appended.
     proxyUrl: config.proxyUrl?.replace(/\/+$/, ""),
-    statusKey: config.statusKey
+    statusKey: config.statusKey,
+    // Dropped unless it can actually be used. A config missing the token, the owner
+    // or the repo would otherwise render a button whose only outcome is an error.
+    unblock: config.unblock?.token && config.unblock.owner && config.unblock.repo ? config.unblock : void 0
   };
 }
 function ConfigProvider({ value, children }) {
@@ -666,8 +669,64 @@ async function fetchDeploymentEvents(transport, target, deploymentId) {
   return data.events ?? [];
 }
 
+// src/lib/github.ts
+var GITHUB_API = "https://api.github.com";
+var DEFAULT_WORKFLOW = "version-bump.yml";
+var SEGMENT_RE = /^[A-Za-z0-9._-]+$/;
+var REF_RE = /^[A-Za-z0-9._\-/]+$/;
+function isValidRef(ref) {
+  if (!ref || ref.length > 255) return false;
+  if (!REF_RE.test(ref)) return false;
+  if (ref.includes("..") || ref.includes("//")) return false;
+  if (ref.startsWith("/") || ref.endsWith("/")) return false;
+  if (ref.startsWith("-") || ref.endsWith(".lock")) return false;
+  return true;
+}
+async function dispatchVersionBump(opts) {
+  const { config, ref, requestedBy } = opts;
+  const workflow = config.workflow ?? DEFAULT_WORKFLOW;
+  if (!config.token) throw new Error("No GitHub token is configured for deploy recovery.");
+  if (!SEGMENT_RE.test(config.owner)) throw new Error(`Invalid repository owner "${config.owner}".`);
+  if (!SEGMENT_RE.test(config.repo)) throw new Error(`Invalid repository name "${config.repo}".`);
+  if (!SEGMENT_RE.test(workflow)) throw new Error(`Invalid workflow filename "${workflow}".`);
+  if (!isValidRef(ref)) throw new Error(`Invalid branch name "${ref}".`);
+  const path = `/repos/${encodeURIComponent(config.owner)}/${encodeURIComponent(config.repo)}/actions/workflows/${encodeURIComponent(workflow)}/dispatches`;
+  const res = await fetch(`${GITHUB_API}${path}`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${config.token}`,
+      Accept: "application/vnd.github+json",
+      "X-GitHub-Api-Version": "2022-11-28",
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({
+      ref,
+      // Workflow inputs are strings; anything else is rejected with a 422.
+      inputs: { requested_by: (requestedBy ?? "a Studio user").slice(0, 80) }
+    })
+  });
+  if (res.status === 204) return;
+  throw new Error(`${dispatchErrorMessage(res.status, workflow, ref)} (GitHub ${res.status})`);
+}
+function dispatchErrorMessage(status, workflow, ref) {
+  switch (status) {
+    case 401:
+      return "The GitHub token is invalid or expired. Ask a developer to reissue it.";
+    case 403:
+      return "The GitHub token is not allowed to run workflows on this repository. It needs Actions: write.";
+    case 404:
+      return `GitHub could not find "${workflow}". It must exist on the repository's default branch as well as on "${ref}" \u2014 or the token cannot see this repository.`;
+    case 422:
+      return `GitHub rejected the request: branch "${ref}" may not exist, or "${workflow}" has no workflow_dispatch trigger.`;
+    case 429:
+      return "GitHub rate limit reached. Wait a minute and try again.";
+    default:
+      return status >= 500 ? "GitHub is having problems. Try again shortly." : "The version bump could not be started.";
+  }
+}
+
 // src/components/DeployItem.tsx
-import { useClient } from "sanity";
+import { useClient, useCurrentUser } from "sanity";
 
 // src/lib/helpers.ts
 function parseHookUrl(url) {
@@ -734,6 +793,11 @@ function stateLabel(state) {
       return { label: "Initializing", tone: "caution" };
     case "ERROR":
       return { label: "Error", tone: "critical" };
+    // Distinct from Error: nothing was built, so there is no log to read and a
+    // retry changes nothing. Labelling it 'Unknown' is what made this failure
+    // invisible to editors, who saw a deploy that simply never arrived.
+    case "BLOCKED":
+      return { label: "Blocked", tone: "critical" };
     case "CANCELED":
       return { label: "Canceled", tone: "default" };
     case "LOADING":
@@ -881,6 +945,7 @@ function DeployItem({ target, token, onDelete, onEdit }) {
   const toast = useToast();
   const pluginConfig = usePluginConfig();
   const client = useClient({ apiVersion: "2025-01-01" });
+  const currentUser = useCurrentUser();
   const transport = useMemo2(
     () => pluginConfig.mode === "proxy" ? { mode: "proxy", proxyUrl: pluginConfig.proxyUrl ?? "", statusKey: pluginConfig.statusKey } : { mode: "direct", token },
     [pluginConfig.mode, pluginConfig.proxyUrl, pluginConfig.statusKey, token]
@@ -903,6 +968,8 @@ function DeployItem({ target, token, onDelete, onEdit }) {
   const [loadingLogs, setLoadingLogs] = useState5(false);
   const [logError, setLogError] = useState5(null);
   const [pollError, setPollError] = useState5(null);
+  const [bumping, setBumping] = useState5(false);
+  const [bumpResult, setBumpResult] = useState5(null);
   const triggeredFromUidRef = useRef2(void 0);
   const requestSeqRef = useRef2(0);
   const mountedRef = useRef2(true);
@@ -1049,6 +1116,35 @@ function DeployItem({ target, token, onDelete, onEdit }) {
     if (!showErrorLogs && errorLines.length === 0 && !logError) fetchErrorLogs();
     setShowErrorLogs((v) => !v);
   }, [showErrorLogs, errorLines.length, logError, fetchErrorLogs]);
+  const requestBump = useCallback4(async () => {
+    const unblockConfig = pluginConfig.unblock;
+    const ref = latest?.meta?.githubCommitRef ?? unblockConfig?.defaultRef;
+    if (!unblockConfig || !ref) return;
+    setBumping(true);
+    setBumpResult(null);
+    try {
+      await dispatchVersionBump({
+        config: unblockConfig,
+        ref,
+        requestedBy: currentUser?.name || currentUser?.email || void 0
+      });
+      setBumpResult({
+        ok: true,
+        message: `Version bump requested on ${ref}. The new deploy appears here in a minute or two.`
+      });
+      toast.push({
+        status: "success",
+        title: "Version bump requested",
+        description: `${target.name} will redeploy once the bump commit lands on ${ref}.`
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "The version bump could not be started.";
+      setBumpResult({ ok: false, message });
+      toast.push({ status: "error", title: "Could not request a version bump", description: message });
+    } finally {
+      setBumping(false);
+    }
+  }, [pluginConfig.unblock, latest?.meta?.githubCommitRef, currentUser, target.name, toast]);
   const branch = latest?.meta?.githubCommitRef;
   const commitMsg = latest?.meta?.githubCommitMessage?.split("\n")[0];
   const sha = shortSha(latest?.meta?.githubCommitSha);
@@ -1058,6 +1154,10 @@ function DeployItem({ target, token, onDelete, onEdit }) {
   const deployedAt = latest?.created ? timeAgo(latest.created) : null;
   const vercelProjectUrl = projectHref(latest?.inspectorUrl);
   const isError = latest?.state === "ERROR";
+  const isBlocked = latest?.state === "BLOCKED";
+  const blockedAuthor = latest?.meta?.githubCommitAuthorLogin ?? latest?.meta?.githubCommitAuthorName;
+  const bumpRef = branch ?? pluginConfig.unblock?.defaultRef;
+  const canUnblock = Boolean(isBlocked && pluginConfig.unblock && bumpRef);
   return /* @__PURE__ */ jsxs6(Fragment, { children: [
     /* @__PURE__ */ jsx10(Card, { radius: 2, shadow: 1, tone: "default", children: /* @__PURE__ */ jsxs6(Flex, { align: "stretch", className: "dvfs-card-flex", children: [
       /* @__PURE__ */ jsxs6(Flex, { direction: "column", flex: 1, style: { minWidth: 0 }, children: [
@@ -1221,7 +1321,48 @@ function DeployItem({ target, token, onDelete, onEdit }) {
                 ] })
               ] }),
               deployError && /* @__PURE__ */ jsx10(Card, { tone: "critical", padding: 2, radius: 2, children: /* @__PURE__ */ jsx10(Text, { size: 1, children: deployError }) })
-            ] })
+            ] }),
+            isBlocked && /* @__PURE__ */ jsx10(Card, { tone: "critical", padding: 3, radius: 2, children: /* @__PURE__ */ jsxs6(Stack, { space: 3, children: [
+              /* @__PURE__ */ jsxs6(Flex, { align: "flex-start", gap: 2, children: [
+                /* @__PURE__ */ jsx10(Box, { style: { flexShrink: 0, marginTop: 2 }, children: /* @__PURE__ */ jsx10(WarningOutlineIcon, { "aria-hidden": "true" }) }),
+                /* @__PURE__ */ jsxs6(Stack, { space: 2, children: [
+                  /* @__PURE__ */ jsx10(Text, { size: 1, weight: "semibold", children: "Vercel refused to build this commit" }),
+                  /* @__PURE__ */ jsxs6(Text, { size: 1, children: [
+                    blockedAuthor ? /* @__PURE__ */ jsxs6(Fragment, { children: [
+                      "The last commit was authored by ",
+                      /* @__PURE__ */ jsx10("strong", { children: blockedAuthor }),
+                      ", who is not a member of the Vercel team, so the build never started."
+                    ] }) : /* @__PURE__ */ jsx10(Fragment, { children: "The last commit's author is not a member of the Vercel team, so the build never started." }),
+                    " ",
+                    "Deploying again will not help \u2014 it rebuilds the same commit."
+                  ] })
+                ] })
+              ] }),
+              canUnblock ? /* @__PURE__ */ jsxs6(Stack, { space: 2, children: [
+                /* @__PURE__ */ jsx10(
+                  Button,
+                  {
+                    text: bumping ? "Requesting\u2026" : "Bump version and redeploy",
+                    tone: "critical",
+                    icon: RocketIcon,
+                    fontSize: 1,
+                    loading: bumping,
+                    disabled: bumping || bumpResult?.ok === true,
+                    onClick: requestBump,
+                    style: { alignSelf: "flex-start", cursor: "pointer" }
+                  }
+                ),
+                /* @__PURE__ */ jsxs6(Text, { size: 0, muted: true, children: [
+                  "Adds an authorised version-bump commit on ",
+                  /* @__PURE__ */ jsx10("code", { children: bumpRef }),
+                  ", which Vercel will build."
+                ] })
+              ] }) : /* @__PURE__ */ jsx10(Text, { size: 0, muted: true, children: pluginConfig.unblock ? "This deployment carries no branch information, so a version bump cannot be targeted. Ask a developer to deploy manually." : "Ask a developer to push a version bump \u2014 a commit by an authorised author is needed before this site can deploy." }),
+              bumpResult && /* @__PURE__ */ jsxs6(Text, { size: 0, weight: bumpResult.ok ? "semibold" : void 0, children: [
+                bumpResult.ok ? "\u2713 " : "",
+                bumpResult.message
+              ] })
+            ] }) })
           ] }),
           pollError && /* @__PURE__ */ jsx10(Card, { tone: "caution", padding: 3, radius: 2, children: /* @__PURE__ */ jsxs6(Flex, { align: "center", gap: 2, children: [
             /* @__PURE__ */ jsx10(WarningOutlineIcon, { "aria-hidden": "true" }),
@@ -1609,7 +1750,7 @@ function DeployTargetForm({ initial, onSaved, onClose }) {
 }
 
 // src/version.ts
-var VERSION = "1.3.2";
+var VERSION = "1.4.0";
 
 // src/components/DeployTool.tsx
 import { jsx as jsx13, jsxs as jsxs9 } from "react/jsx-runtime";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liiift-studio/deploy-vercel-from-sanity",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "Sanity Studio plugin — trigger and monitor Vercel deployments with full status, history, and build logs. Supports Studio v3.30 through v6.",
   "license": "MIT",
   "author": "Liiift Studio",