@kungfu-tech/buildchain 2.4.3 → 2.4.4-alpha.1

package/docs/web-surface-deployments.md

@@ -431,6 +431,7 @@ jobs:
       production-release-on-main: false
       production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions
       production-environment: production
+      release-feedback-actor-privacy: public
 ```
 
 When enabled, Buildchain owns the full release apply state machine:
@@ -440,13 +441,37 @@ When enabled, Buildchain owns the full release apply state machine:
 - Closed PR cleanup runs `cleanup-apply --dry-run false` with the preview role
   only.
 - Pushes to `main` run staging `deploy-apply --dry-run false` with the staging
-  role.
+  role, then write a staging release feedback passport artifact and comment the
+  associated merged PR with the staging URL, source SHA, artifact identity, run
+  URL, and failure context when apply did not complete.
+- Release pull requests that match the configured production gate get a
+  Buildchain review comment with the staging URL and production target, so the
+  operator can verify staging from the PR page and use merge as the approval
+  action.
 - Production runs when `production-apply` is true and either:
   - a trusted `workflow_dispatch` passes `production-approved=true`; or
   - `production-release-on-main=true` and the `main` push commit is associated
     with exactly one same-repository, merged release pull request matching
     `production-release-label` and `production-release-head-prefix`.
   The production job is then gated by the configured GitHub Environment.
+- Production apply writes a production release feedback passport artifact and
+  comments the release PR with the production URL, source SHA, artifact
+  identity, run URL, rollback pointer, and failure context when apply did not
+  complete.
+
+The feedback passport records the release responsibility chain:
+
+- human decision actor;
+- trigger actor;
+- runner/execution actor;
+- OIDC/deploy identity reference;
+- decision type and time;
+- source event, PR number, merge commit, and required gate label/head-prefix.
+
+`release-feedback-actor-privacy` controls actor values in the passport and
+comments. `public` records GitHub actor names, `redacted` records only the actor
+role, and `private-ref` records a stable private reference hash without exposing
+the actor name.
 
 For release-PR publishing, callers opt in explicitly:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.4.3",
+  "version": "2.4.4-alpha.1",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/packages/core/release-passport.js

@@ -537,6 +537,24 @@ export function createReleasePassport({
     normalizedTransaction?.releaseSha,
   );
   const targetRef = optionalString(release.targetRef || release.target_ref || normalizedPublishEvidence?.targetRef);
+  const packageDisplayVersion = optionalString(
+    packageVersion ||
+    normalizedPackageSet?.main?.version ||
+    normalizedPublishSummary?.packages?.find((entry) => entry.role === "main")?.publishedVersion ||
+    normalizedPublishEvidence?.version ||
+    normalizedTransaction?.version ||
+    readPackageVersion(cwd),
+  );
+  const publishedVersion = optionalString(
+    release.publishedVersion ||
+    release.published_version ||
+    packageDisplayVersion,
+  );
+  const internalVersion = optionalString(
+    release.internalVersion ||
+    release.internal_version ||
+    normalizedTransaction?.version,
+  );
   return {
     schemaVersion: 1,
     contract: RELEASE_PASSPORT_CONTRACT,
@@ -548,6 +566,10 @@ export function createReleasePassport({
     },
     release: {
       tag: normalizedTag,
+      internalTag: optionalString(release.internalTag || release.internal_tag || normalizedTag),
+      internalVersion,
+      publishedVersion,
+      versionLabel: optionalString(release.versionLabel || release.version_label || publishedVersion || normalizedTag),
       line: optionalString(line),
       sourceSha: optionalString(sourceSha),
       channel: optionalString(release.channel || normalizedPublishEvidence?.channel || publish.channel),
@@ -568,7 +590,7 @@ export function createReleasePassport({
       releaseStateSha: optionalString(release.releaseStateSha || release.release_state_sha || normalizedTransaction?.stateSha),
       package: {
         name: packageName,
-        version: packageVersion || readPackageVersion(cwd),
+        version: packageDisplayVersion,
       },
       exactRef: normalizedTag ? `refs/tags/${normalizedTag}` : "",
     },

package/scripts/web-surface-release-feedback.mjs

@@ -0,0 +1,342 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { upsertIssueComment } from "./web-surface-release-pr-review.mjs";
+
+export const RELEASE_FEEDBACK_MARKERS = {
+  staging: "<!-- buildchain:web-surface-release-feedback:staging -->",
+  production: "<!-- buildchain:web-surface-release-feedback:production -->",
+};
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function optionalString(value = "") {
+  return String(value || "").trim();
+}
+
+function asBool(value) {
+  return value === true || value === "true";
+}
+
+function readJsonIfExists(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) return undefined;
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function runUrl({ serverUrl = "", repository = "", runId = "" } = {}) {
+  if (!serverUrl || !repository || !runId) return "";
+  return `${serverUrl.replace(/\/$/, "")}/${repository}/actions/runs/${runId}`;
+}
+
+function privateActorRef(actor = "", kind = "actor") {
+  const value = optionalString(actor);
+  if (!value) return "";
+  const digest = crypto.createHash("sha256").update(`${kind}:${value}`).digest("hex").slice(0, 16);
+  return `private-ref:sha256:${digest}`;
+}
+
+export function normalizeActorIdentity(actor = "", { privacyMode = "public", kind = "actor" } = {}) {
+  const value = optionalString(actor);
+  if (!value) return "";
+  if (privacyMode === "redacted") return `${kind}:redacted`;
+  if (privacyMode === "private-ref") return privateActorRef(value, kind);
+  return value;
+}
+
+function urlsFromResult(result = {}) {
+  const urls = result.urls && typeof result.urls === "object" ? result.urls : {};
+  if (Object.keys(urls).length > 0) return urls;
+  return result.url ? { default: result.url } : {};
+}
+
+function inferStatus({ result, applyOutcome = "", jobStatus = "" } = {}) {
+  if (result?.status) return result.status;
+  if (applyOutcome === "success" || jobStatus === "success") return "success";
+  if (applyOutcome || jobStatus) return "failure";
+  return "unknown";
+}
+
+function eventTimestamp(payload = {}) {
+  return (
+    payload.pull_request?.merged_at ||
+    payload.pull_request?.updated_at ||
+    payload.head_commit?.timestamp ||
+    payload.repository?.pushed_at ||
+    nowIso()
+  );
+}
+
+async function githubJson({ apiUrl = "https://api.github.com", token, url, fetchImpl = fetch }) {
+  if (!token) throw new Error("GITHUB_TOKEN is required to resolve associated pull requests");
+  const response = await fetchImpl(url.startsWith("http") ? url : `${apiUrl.replace(/\/$/, "")}${url}`, {
+    headers: {
+      accept: "application/vnd.github+json",
+      authorization: `Bearer ${token}`,
+      "x-github-api-version": "2022-11-28",
+    },
+  });
+  if (!response.ok) {
+    throw new Error(`GitHub API request failed: HTTP ${response.status}`);
+  }
+  return response.json();
+}
+
+export async function resolveFeedbackTarget({
+  payload = {},
+  repository = "",
+  commitSha = "",
+  releasePullNumber = "",
+  releasePullSource = "",
+  apiUrl = "https://api.github.com",
+  token = "",
+  fetchImpl = fetch,
+} = {}) {
+  const explicitNumber = optionalString(releasePullNumber);
+  if (explicitNumber) {
+    return {
+      shouldComment: true,
+      pullNumber: Number(explicitNumber),
+      source: "release-intent",
+      sourceBranch: releasePullSource,
+    };
+  }
+
+  const payloadPull = payload.pull_request;
+  if (payloadPull?.number) {
+    return {
+      shouldComment: true,
+      pullNumber: Number(payloadPull.number),
+      source: "event-pull-request",
+      sourceBranch: payloadPull.head?.ref || "",
+    };
+  }
+
+  if (!repository || !commitSha || !repository.includes("/")) {
+    return { shouldComment: false, reason: "missing-repository-or-commit" };
+  }
+
+  const [owner, repo] = repository.split("/");
+  const associated = await githubJson({
+    apiUrl,
+    token,
+    fetchImpl,
+    url: `/repos/${owner}/${repo}/commits/${commitSha}/pulls?per_page=100`,
+  });
+  const sameRepo = `${owner}/${repo}`;
+  const candidates = associated.filter((pull) => (
+    pull.merged_at &&
+    pull.base?.ref === "main" &&
+    pull.head?.repo?.full_name === sameRepo
+  ));
+  if (candidates.length !== 1) {
+    return {
+      shouldComment: false,
+      reason: candidates.length === 0 ? "no-associated-merged-pr" : "multiple-associated-merged-prs",
+      candidatePulls: candidates.map((pull) => pull.number),
+    };
+  }
+  return {
+    shouldComment: true,
+    pullNumber: Number(candidates[0].number),
+    source: "associated-merged-pr",
+    sourceBranch: candidates[0].head?.ref || "",
+  };
+}
+
+export function createWebSurfaceReleasePassport({
+  channel = "staging",
+  repository = "",
+  productName = "",
+  sourceSha = "",
+  result = undefined,
+  status = "unknown",
+  applyOutcome = "",
+  jobStatus = "",
+  runId = "",
+  runAttempt = "",
+  runUrl: workflowRunUrl = "",
+  runtimeSha = "",
+  rollbackPointer = "",
+  payload = {},
+  sourceEvent = "",
+  target = {},
+  gate = {},
+  privacyMode = "public",
+  actor = "",
+  triggeringActor = "",
+  runnerActor = "",
+  oidcDeployIdentity = "",
+} = {}) {
+  const normalizedStatus = inferStatus({ result, applyOutcome, jobStatus }) || status;
+  const decisionType = channel === "production" ? "release-pr-merge-or-manual-approval" : "main-merge-staging";
+  const normalizedResult = result || {};
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-web-surface-release-passport",
+    generatedAt: nowIso(),
+    product: {
+      name: optionalString(productName || repository.split("/").pop() || "web-surface"),
+      repository: optionalString(repository),
+      type: "web-surface",
+    },
+    release: {
+      channel: optionalString(channel),
+      sourceSha: optionalString(normalizedResult.sourceSha || sourceSha),
+      status: normalizedStatus,
+      url: optionalString(normalizedResult.url),
+      urls: urlsFromResult(normalizedResult),
+      artifactHash: optionalString(normalizedResult.artifactHash),
+      target: optionalString(normalizedResult.target),
+      manifestKey: optionalString(normalizedResult.manifestKey),
+      runtimeSha: optionalString(runtimeSha || normalizedResult.manifest?.runtimeId),
+      rollbackPointer: optionalString(rollbackPointer || normalizedResult.manifest?.rollbackPointer),
+    },
+    responsibility: {
+      privacyMode,
+      humanDecisionActor: normalizeActorIdentity(actor, { privacyMode, kind: "human-decision-actor" }),
+      triggerActor: normalizeActorIdentity(triggeringActor || actor, { privacyMode, kind: "trigger-actor" }),
+      runnerExecutionActor: normalizeActorIdentity(runnerActor || actor, { privacyMode, kind: "runner-execution-actor" }),
+      oidcDeployIdentity: optionalString(oidcDeployIdentity),
+      decisionType,
+      decidedAt: eventTimestamp(payload),
+      sourceEvent: optionalString(sourceEvent || payload.action || (payload.ref ? "push" : "")),
+      pullRequest: target.pullNumber ? Number(target.pullNumber) : null,
+      mergeCommit: optionalString(sourceSha),
+      requiredGateEvidence: {
+        label: optionalString(gate.label),
+        headPrefix: optionalString(gate.headPrefix),
+        sourceBranch: optionalString(target.sourceBranch),
+        targetResolution: optionalString(target.source || target.reason),
+      },
+    },
+    workflow: {
+      runId: optionalString(runId),
+      runAttempt: optionalString(runAttempt),
+      url: optionalString(workflowRunUrl),
+      applyOutcome: optionalString(applyOutcome),
+      jobStatus: optionalString(jobStatus),
+    },
+    evidence: {
+      applyResultBound: Boolean(result),
+      failureContext: normalizedStatus === "success" ? "" : optionalString(applyOutcome || jobStatus || "missing-apply-result"),
+    },
+  };
+}
+
+export function renderWebSurfaceReleaseFeedbackComment({
+  channel = "staging",
+  passport = {},
+  target = {},
+  passportArtifact = "",
+} = {}) {
+  const marker = RELEASE_FEEDBACK_MARKERS[channel] || `<!-- buildchain:web-surface-release-feedback:${channel} -->`;
+  const release = passport.release || {};
+  const urls = release.urls && Object.keys(release.urls).length > 0 ? release.urls : (release.url ? { default: release.url } : {});
+  const urlLines = Object.entries(urls).map(([surface, url]) => `- ${surface}: ${url}`);
+  const status = release.status || "unknown";
+  const title = channel === "production" ? "Buildchain production deploy" : "Buildchain staging deploy";
+  const failure = passport.evidence?.failureContext ? [`- Failure context: \`${passport.evidence.failureContext}\``] : [];
+  const targetLine = target.pullNumber ? `- Comment target: PR #${target.pullNumber}` : "";
+  return [
+    marker,
+    `## ${title}`,
+    "",
+    `- Status: \`${status}\``,
+    ...urlLines,
+    `- Source: \`${release.sourceSha || ""}\``,
+    `- Artifact: \`${release.artifactHash || ""}\``,
+    `- Target: \`${release.target || ""}\``,
+    `- Rollback pointer: \`${release.rollbackPointer || ""}\``,
+    `- Run: ${passport.workflow?.url || ""}`,
+    `- Passport artifact: \`${passportArtifact || "buildchain-web-surface-release-passport"}\``,
+    targetLine,
+    ...failure,
+  ].filter((line) => line !== "").join("\n");
+}
+
+export async function webSurfaceReleaseFeedbackCli(env = process.env, { fetchImpl = fetch } = {}) {
+  const eventPath = env.GITHUB_EVENT_PATH;
+  if (!eventPath) throw new Error("GITHUB_EVENT_PATH is required");
+  const payload = JSON.parse(fs.readFileSync(eventPath, "utf8"));
+  const channel = optionalString(env.BUILDCHAIN_WEB_SURFACE_CHANNEL || "staging");
+  const result = readJsonIfExists(env.APPLY_RESULT_PATH || "");
+  const repository = optionalString(env.GITHUB_REPOSITORY);
+  const sourceSha = optionalString(result?.sourceSha || env.GITHUB_SHA);
+  const workflowRunUrl = runUrl({
+    serverUrl: env.GITHUB_SERVER_URL,
+    repository,
+    runId: env.GITHUB_RUN_ID,
+  });
+  const target = await resolveFeedbackTarget({
+    payload,
+    repository,
+    commitSha: sourceSha,
+    releasePullNumber: env.PRODUCTION_RELEASE_PR,
+    releasePullSource: env.PRODUCTION_RELEASE_SOURCE,
+    apiUrl: env.GITHUB_API_URL || "https://api.github.com",
+    token: env.GITHUB_TOKEN,
+    fetchImpl,
+  });
+  const passport = createWebSurfaceReleasePassport({
+    channel,
+    repository,
+    productName: env.PRODUCT_NAME,
+    sourceSha,
+    result,
+    applyOutcome: env.APPLY_STEP_OUTCOME,
+    jobStatus: env.JOB_STATUS,
+    runId: env.GITHUB_RUN_ID,
+    runAttempt: env.GITHUB_RUN_ATTEMPT,
+    runUrl: workflowRunUrl,
+    runtimeSha: env.BUILDCHAIN_RUNTIME_SHA,
+    rollbackPointer: env.BUILDCHAIN_ROLLBACK_POINTER,
+    payload,
+    sourceEvent: env.GITHUB_EVENT_NAME,
+    target,
+    gate: {
+      label: env.PRODUCTION_RELEASE_LABEL,
+      headPrefix: env.PRODUCTION_RELEASE_HEAD_PREFIX,
+    },
+    privacyMode: optionalString(env.RELEASE_FEEDBACK_ACTOR_PRIVACY || "public"),
+    actor: env.GITHUB_ACTOR,
+    triggeringActor: env.GITHUB_TRIGGERING_ACTOR,
+    runnerActor: env.RUNNER_NAME || env.GITHUB_ACTOR,
+    oidcDeployIdentity: env.DEPLOY_IDENTITY_REF || env.AWS_ROLE_ARN,
+  });
+  const outputPath = env.OUTPUT_PATH || `.buildchain/web-surface-${channel}-release-passport.json`;
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, `${JSON.stringify(passport, null, 2)}\n`);
+
+  const artifactName = env.PASSPORT_ARTIFACT_NAME || `buildchain-web-surface-${channel}-release-passport`;
+  if (!target.shouldComment) {
+    console.log(`web-surface release feedback comment skipped: ${target.reason}`);
+    return { passport, target, outputPath, comment: { action: "skipped", reason: target.reason } };
+  }
+  const body = renderWebSurfaceReleaseFeedbackComment({
+    channel,
+    passport,
+    target,
+    passportArtifact: artifactName,
+  });
+  const comment = await upsertIssueComment({
+    apiUrl: env.GITHUB_API_URL || "https://api.github.com",
+    token: env.GITHUB_TOKEN,
+    repository,
+    issueNumber: target.pullNumber,
+    body,
+    marker: RELEASE_FEEDBACK_MARKERS[channel],
+    fetchImpl,
+  });
+  console.log(`web-surface release feedback comment ${comment.action}: ${comment.commentId}`);
+  return { passport, target, outputPath, comment };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  webSurfaceReleaseFeedbackCli().catch((error) => {
+    console.error(error.stack || error.message);
+    process.exitCode = 1;
+  });
+}

package/scripts/web-surface-release-pr-review.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseToml } from "smol-toml";
+
+export const RELEASE_REVIEW_MARKER = "<!-- buildchain:web-surface-release-review -->";
+
+export function resolveReleaseReviewState(payload, options = {}) {
+  const eventName = options.eventName || "";
+  const eventAction = options.eventAction || "";
+  const repository = options.repository || "";
+  const enabled = options.productionReleaseOnMain === true || options.productionReleaseOnMain === "true";
+  const requiredLabel = String(options.productionReleaseLabel || "").trim();
+  const requiredHeadPrefix = String(options.productionReleaseHeadPrefix || "").trim();
+  const pull = payload?.pull_request;
+
+  if (!enabled) return { shouldComment: false, reason: "release-pr-publish-disabled" };
+  if (eventName !== "pull_request") return { shouldComment: false, reason: "not-a-pull-request" };
+  if (eventAction === "closed") return { shouldComment: false, reason: "pull-request-closed" };
+  if (!pull) return { shouldComment: false, reason: "missing-pull-request-payload" };
+  if (!requiredLabel) return { shouldComment: false, reason: "missing-production-release-label" };
+
+  const labels = (pull.labels || []).map((label) => label.name).filter(Boolean);
+  if (!labels.includes(requiredLabel)) {
+    return { shouldComment: false, reason: "missing-release-label" };
+  }
+
+  const baseRef = pull.base?.ref || "";
+  if (baseRef !== "main") {
+    return { shouldComment: false, reason: "base-is-not-main" };
+  }
+
+  const headRef = pull.head?.ref || "";
+  if (requiredHeadPrefix && !headRef.startsWith(requiredHeadPrefix)) {
+    return { shouldComment: false, reason: "head-prefix-mismatch" };
+  }
+
+  const headRepo = pull.head?.repo?.full_name || "";
+  if (repository && headRepo && headRepo !== repository) {
+    return { shouldComment: false, reason: "head-repo-mismatch" };
+  }
+
+  return {
+    shouldComment: true,
+    reason: "release-pr-review-ready",
+    pullNumber: pull.number,
+    headRef,
+    baseRef,
+    labels,
+  };
+}
+
+export function loadWebSurfaceReleaseUrls(cwd = ".") {
+  const configPath = path.join(cwd, "buildchain.toml");
+  const raw = fs.readFileSync(configPath, "utf8");
+  const config = parseToml(raw);
+  const stagingUrl = String(config.channels?.staging?.url || "").trim();
+  const productionUrl = String(config.channels?.production?.url || "").trim();
+  if (!stagingUrl) {
+    throw new Error("channels.staging.url is required for a release PR review comment");
+  }
+  if (!productionUrl) {
+    throw new Error("channels.production.url is required for a release PR review comment");
+  }
+  return { stagingUrl, productionUrl };
+}
+
+export function renderReleaseReviewComment({
+  stagingUrl,
+  productionUrl,
+  label,
+  headPrefix,
+}) {
+  const branchLine = headPrefix
+    ? `- Release branch prefix: \`${headPrefix}\``
+    : "- Release branch prefix: `(none)`";
+  return `${RELEASE_REVIEW_MARKER}
+## Buildchain release review
+
+- Staging review URL: ${stagingUrl}
+- Production target: ${productionUrl}
+- Approval action: merge this release PR after staging has been verified.
+- Release label: \`${label}\`
+${branchLine}
+
+Buildchain treats this merge as the production approval event. The resulting
+\`main\` push will publish production only after Buildchain verifies the merged
+same-repository release PR, the required label, and the release branch prefix.`;
+}
+
+export async function upsertIssueComment({
+  apiUrl = "https://api.github.com",
+  token,
+  repository,
+  issueNumber,
+  body,
+  marker = RELEASE_REVIEW_MARKER,
+  fetchImpl = fetch,
+}) {
+  if (!token) throw new Error("GITHUB_TOKEN is required to write the release PR review comment");
+  if (!repository || !repository.includes("/")) throw new Error("GITHUB_REPOSITORY must be owner/repo");
+  if (!issueNumber) throw new Error("pull request number is required to write a comment");
+
+  const [owner, repo] = repository.split("/");
+  const base = apiUrl.replace(/\/$/, "");
+  const headers = {
+    accept: "application/vnd.github+json",
+    authorization: `Bearer ${token}`,
+    "content-type": "application/json",
+    "x-github-api-version": "2022-11-28",
+  };
+
+  const commentsUrl = `${base}/repos/${owner}/${repo}/issues/${issueNumber}/comments?per_page=100`;
+  const commentsResponse = await fetchImpl(commentsUrl, { headers });
+  if (!commentsResponse.ok) {
+    throw new Error(`failed to list release PR comments: HTTP ${commentsResponse.status}`);
+  }
+  const comments = await commentsResponse.json();
+  const existing = comments.find((comment) => String(comment.body || "").includes(marker));
+
+  if (existing) {
+    const updateResponse = await fetchImpl(`${base}/repos/${owner}/${repo}/issues/comments/${existing.id}`, {
+      method: "PATCH",
+      headers,
+      body: JSON.stringify({ body }),
+    });
+    if (!updateResponse.ok) {
+      throw new Error(`failed to update release PR comment: HTTP ${updateResponse.status}`);
+    }
+    return { action: "updated", commentId: existing.id };
+  }
+
+  const createResponse = await fetchImpl(`${base}/repos/${owner}/${repo}/issues/${issueNumber}/comments`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ body }),
+  });
+  if (!createResponse.ok) {
+    throw new Error(`failed to create release PR comment: HTTP ${createResponse.status}`);
+  }
+  const created = await createResponse.json();
+  return { action: "created", commentId: created.id };
+}
+
+export async function webSurfaceReleasePrReviewCli(env = process.env) {
+  const eventPath = env.GITHUB_EVENT_PATH;
+  if (!eventPath) throw new Error("GITHUB_EVENT_PATH is required");
+  const payload = JSON.parse(fs.readFileSync(eventPath, "utf8"));
+  const state = resolveReleaseReviewState(payload, {
+    eventName: env.GITHUB_EVENT_NAME,
+    eventAction: env.GITHUB_EVENT_ACTION,
+    repository: env.GITHUB_REPOSITORY,
+    productionReleaseOnMain: env.PRODUCTION_RELEASE_ON_MAIN,
+    productionReleaseLabel: env.PRODUCTION_RELEASE_LABEL,
+    productionReleaseHeadPrefix: env.PRODUCTION_RELEASE_HEAD_PREFIX,
+  });
+
+  if (!state.shouldComment) {
+    console.log(`release PR review comment skipped: ${state.reason}`);
+    return state;
+  }
+
+  const { stagingUrl, productionUrl } = loadWebSurfaceReleaseUrls(env.WORKING_DIRECTORY || ".");
+  const body = renderReleaseReviewComment({
+    stagingUrl,
+    productionUrl,
+    label: env.PRODUCTION_RELEASE_LABEL,
+    headPrefix: env.PRODUCTION_RELEASE_HEAD_PREFIX,
+  });
+  const result = await upsertIssueComment({
+    apiUrl: env.GITHUB_API_URL || "https://api.github.com",
+    token: env.GITHUB_TOKEN,
+    repository: env.GITHUB_REPOSITORY,
+    issueNumber: state.pullNumber,
+    body,
+  });
+  console.log(`release PR review comment ${result.action}: ${result.commentId}`);
+  return { ...state, ...result };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  webSurfaceReleasePrReviewCli().catch((error) => {
+    console.error(error.stack || error.message);
+    process.exitCode = 1;
+  });
+}