@kungfu-tech/buildchain 3.0.2 → 3.0.3-alpha.1

package/packages/core/release-propagation.js

@@ -5,6 +5,7 @@ import path from "node:path";
 export const RELEASE_PROPAGATION_GRAPH_CONTRACT = "kungfu-buildchain-release-propagation-graph";
 export const RELEASE_PROPAGATION_PLAN_CONTRACT = "kungfu-buildchain-release-propagation-plan";
 export const RELEASE_PROPAGATION_LOCK_CONTRACT = "kungfu-buildchain-release-propagation-lock";
+export const RELEASE_PROPAGATION_RECEIPT_CONTRACT = "kungfu-buildchain-release-propagation-receipt";
 
 const SUPPORTED_CHANNELS = new Set(["alpha", "release"]);
 const SUPPORTED_CHANNEL_POLICIES = new Set(["preserve", "explicit"]);
@@ -31,6 +32,49 @@ function sha256Json(value) {
   return crypto.createHash("sha256").update(stableJson(value)).digest("hex");
 }
 
+function releaseVersion(upstreamRelease) {
+  return upstreamRelease.package?.version || upstreamRelease.publicationArtifact?.version || "";
+}
+
+function safeBranchPart(value) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9._-]+/g, "-")
+    .replaceAll(/^-+|-+$/g, "");
+  if (!normalized) {
+    throw new Error(`release propagation branch component is empty: ${value}`);
+  }
+  return normalized;
+}
+
+function releaseIdentity(upstreamRelease) {
+  const version = releaseVersion(upstreamRelease);
+  if (!version) {
+    throw new Error("upstream release does not expose a package or publication version");
+  }
+  return {
+    repository: upstreamRelease.repository,
+    version,
+    channel: upstreamRelease.channel,
+  };
+}
+
+function propagationIdentity({ upstreamRelease, targetNode }) {
+  return {
+    release: releaseIdentity(upstreamRelease),
+    downstreamRepository: targetNode.repository,
+  };
+}
+
+function propagationBranch({ upstreamRelease, targetNode }) {
+  const identity = propagationIdentity({ upstreamRelease, targetNode });
+  const digest = sha256Json(identity).slice(0, 12);
+  const repository = safeBranchPart(upstreamRelease.repository.replace("/", "-"));
+  const version = safeBranchPart(releaseVersion(upstreamRelease));
+  return `buildchain/release-propagation/${repository}/${version}-${upstreamRelease.channel}-${digest}`;
+}
+
 function assertPlainObject(value, label) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new Error(`${label} must be an object`);
@@ -305,6 +349,8 @@ export function createReleasePropagationLock({
   upstreamRelease,
   downstreamChannel,
 } = {}) {
+  const identity = propagationIdentity({ upstreamRelease, targetNode });
+  const propagationKey = sha256Json(identity);
   const lock = {
     schemaVersion: 1,
     contract: RELEASE_PROPAGATION_LOCK_CONTRACT,
@@ -331,6 +377,9 @@ export function createReleasePropagationLock({
       edge: edge.id,
       channelPolicy: edge.channelPolicy,
       channelMap: edge.channelMap,
+      releaseIdentity: identity.release,
+      propagationKey,
+      branch: propagationBranch({ upstreamRelease, targetNode }),
       exact: true,
       floatingTags: false,
     },
@@ -374,6 +423,8 @@ export function planReleasePropagation({ graph: graphInput, upstreamRelease: rel
       channel: downstreamChannel,
       baseRef: lock.downstream.baseRef,
       lockPath: lock.downstream.lockPath,
+      propagationKey: lock.propagation.propagationKey,
+      branch: lock.propagation.branch,
       lock,
     });
   }
@@ -387,6 +438,7 @@ export function planReleasePropagation({ graph: graphInput, upstreamRelease: rel
       targetCount: targets.length,
       channels: [...new Set(targets.map((target) => target.channel))],
       repositories: targets.map((target) => target.repository),
+      releaseIdentity: releaseIdentity(upstreamRelease),
     },
   };
 }
@@ -411,13 +463,135 @@ export function writeReleasePropagationLock({ plan, target = "", cwd = process.c
   }
   const selected = matches[0];
   const outputPath = path.resolve(cwd, output || selected.lockPath);
+  const rendered = stableJson(selected.lock);
+  const previous = fs.existsSync(outputPath) ? fs.readFileSync(outputPath, "utf8") : "";
   fs.mkdirSync(path.dirname(outputPath), { recursive: true });
-  fs.writeFileSync(outputPath, stableJson(selected.lock));
+  if (previous !== rendered) {
+    fs.writeFileSync(outputPath, rendered);
+  }
   return {
     target: selected.target,
     repository: selected.repository,
     channel: selected.channel,
     path: outputPath,
     lockSha256: selected.lock.lockSha256,
+    propagationKey: selected.propagationKey || selected.lock.propagation?.propagationKey || "",
+    branch: selected.branch || selected.lock.propagation?.branch || "",
+    status: previous === rendered ? "reused" : "written",
+    changed: previous !== rendered,
+  };
+}
+
+const RECEIPT_VISIBILITY_STATES = new Set(["pending", "visible", "failed", "not-requested"]);
+const RECEIPT_PR_STATES = new Set(["planned", "created", "updated", "reused", "no-change", "failed"]);
+
+function receiptVisibilityState(value, label) {
+  const state = optionalString(value) || "pending";
+  if (!RECEIPT_VISIBILITY_STATES.has(state)) {
+    throw new Error(`${label} must be pending, visible, failed, or not-requested`);
+  }
+  return state;
+}
+
+function receiptPrOutcome(value = {}) {
+  const outcome = assertPlainObject(value, "release propagation PR outcome");
+  const state = optionalString(outcome.state) || "planned";
+  if (!RECEIPT_PR_STATES.has(state)) {
+    throw new Error("release propagation PR outcome state is unsupported");
+  }
+  return {
+    state,
+    number: outcome.number === undefined || outcome.number === null || outcome.number === ""
+      ? null
+      : Number(outcome.number),
+    url: optionalString(outcome.url),
+    branch: assertString(outcome.branch, "release propagation PR outcome branch"),
+  };
+}
+
+export function createReleasePropagationReceipt({
+  plan,
+  target = "",
+  lockResult,
+  prOutcome,
+  stagingState = "pending",
+  productionState = "not-requested",
+  observedAt = "",
+} = {}) {
+  const selectedPlan = assertPlainObject(plan, "plan");
+  const matches = selectedPlan.targets.filter((entry) =>
+    !target || entry.target === target || entry.repository === target);
+  if (matches.length !== 1) {
+    throw new Error(`expected exactly one propagation target, found ${matches.length}`);
+  }
+  const selected = matches[0];
+  const result = assertPlainObject(lockResult, "release propagation lock result");
+  if (result.lockSha256 !== selected.lock.lockSha256) {
+    throw new Error("release propagation receipt lock result does not match the plan");
+  }
+  const propagationKey = selected.propagationKey || selected.lock.propagation?.propagationKey || "";
+  if (result.propagationKey && result.propagationKey !== propagationKey) {
+    throw new Error("release propagation receipt key does not match the lock result");
+  }
+  const branch = selected.branch || selected.lock.propagation?.branch || "";
+  const normalizedPr = receiptPrOutcome({ ...prOutcome, branch: prOutcome?.branch || branch });
+  if (normalizedPr.branch !== branch) {
+    throw new Error("release propagation PR branch does not match the exact plan");
+  }
+  const upstreamRelease = selectedPlan.upstreamRelease;
+  const release = releaseIdentity(upstreamRelease);
+  const states = {
+    "package-published": {
+      state: upstreamRelease.package ? "complete" : "not-applicable",
+      evidence: upstreamRelease.package
+        ? {
+            name: upstreamRelease.package.name,
+            version: upstreamRelease.package.version,
+            integrity: upstreamRelease.package.integrity,
+          }
+        : null,
+    },
+    "alpha-complete": {
+      state: release.channel === "alpha" ? "complete" : "not-applicable",
+      evidence: release.channel === "alpha"
+        ? {
+            releasePassportSha256: upstreamRelease.releasePassport.sha256,
+            tag: upstreamRelease.tag,
+          }
+        : null,
+    },
+    "staging-visible": {
+      state: receiptVisibilityState(stagingState, "stagingState"),
+    },
+    "production-visible": {
+      state: receiptVisibilityState(productionState, "productionState"),
+    },
+  };
+  const body = {
+    schemaVersion: 1,
+    contract: RELEASE_PROPAGATION_RECEIPT_CONTRACT,
+    propagationKey,
+    observedAt: optionalString(observedAt),
+    release,
+    upstream: {
+      repository: upstreamRelease.repository,
+      tag: upstreamRelease.tag,
+      sourceSha: upstreamRelease.sourceSha,
+      releasePassport: upstreamRelease.releasePassport,
+    },
+    downstream: {
+      repository: selected.repository,
+      channel: selected.channel,
+      baseRef: selected.baseRef,
+      lockPath: selected.lockPath,
+      lockSha256: result.lockSha256,
+      lockWriteState: result.status || (result.changed === false ? "reused" : "written"),
+      pullRequest: normalizedPr,
+    },
+    states,
+  };
+  return {
+    ...body,
+    receiptSha256: sha256Json(body),
   };
 }

package/packages/core/stable-release-gate.js

@@ -194,12 +194,14 @@ export function evaluateStableReleaseGate({
       : undefined;
     const attestorAllowed = required.allowedAttestors.length === 0 ||
       required.allowedAttestors.includes(string(evidence?.attestor));
+    const completionTimingValid = required.source === "release-candidate" ||
+      (completedAt && completedAt.milliseconds >= candidatePublished.milliseconds);
     const valid = Boolean(
       evidence &&
       string(evidence.status) === "success" &&
       string(evidence.candidateSha) === candidateSha &&
       completedAt &&
-      completedAt.milliseconds >= candidatePublished.milliseconds &&
+      completionTimingValid &&
       attestorAllowed,
     );
     if (completedAt) {
@@ -222,6 +224,7 @@ export function evaluateStableReleaseGate({
         evidenceUrl: string(evidence?.evidenceUrl),
         attestor: string(evidence?.attestor),
         attestorAllowed,
+        completionTimingValid: Boolean(completionTimingValid),
       },
     ));
   }

package/scripts/artifact-signing-delegation.mjs

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { writeGitHubOutputs } from "./build-contract-core.mjs";
+
+const CONTRACT = "kungfu-buildchain-artifact-signing-delegation/v1";
+
+function required(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${label} is required`);
+  if (/[\r\n\0]/u.test(normalized))
+    throw new Error(`${label} contains control characters`);
+  return normalized;
+}
+
+function optional(value, label) {
+  const normalized = String(value || "").trim();
+  if (/[\r\n\0]/u.test(normalized))
+    throw new Error(`${label} contains control characters`);
+  return normalized;
+}
+
+function exactSha(value, label) {
+  const normalized = required(value, label);
+  if (!/^[0-9a-f]{40}$/u.test(normalized))
+    throw new Error(`${label} must be an exact SHA`);
+  return normalized;
+}
+
+function positiveInteger(value, label, { allowZero = false } = {}) {
+  const normalized = Number(value);
+  if (!Number.isSafeInteger(normalized) || normalized < (allowZero ? 0 : 1)) {
+    throw new Error(
+      `${label} must be ${allowZero ? "a non-negative" : "a positive"} integer`,
+    );
+  }
+  return normalized;
+}
+
+function repository(value, label) {
+  const normalized = required(value, label);
+  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/u.test(normalized)) {
+    throw new Error(`${label} must be owner/repository`);
+  }
+  return normalized;
+}
+
+function safeRelativePath(value, label) {
+  const normalized = required(value, label).replaceAll("\\", "/");
+  const resolved = path.posix.normalize(normalized);
+  if (
+    resolved === ".." ||
+    resolved.startsWith("../") ||
+    path.posix.isAbsolute(resolved)
+  ) {
+    throw new Error(`${label} must be a safe relative path`);
+  }
+  if (!/^[A-Za-z0-9._ /-]+$/u.test(resolved))
+    throw new Error(`${label} contains unsafe shell characters`);
+  return resolved;
+}
+
+export function validateArtifactSigningDelegation(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("delegation must be an object");
+  if (value.schemaVersion !== 1 || value.contract !== CONTRACT)
+    throw new Error("artifact signing delegation contract mismatch");
+  const requestCount = positiveInteger(value.request?.count, "request.count", {
+    allowZero: true,
+  });
+  const delegation = {
+    schemaVersion: 1,
+    contract: CONTRACT,
+    source: {
+      repository: repository(value.source?.repository, "source.repository"),
+      runId: required(value.source?.runId, "source.runId"),
+      runAttempt: positiveInteger(
+        value.source?.runAttempt,
+        "source.runAttempt",
+      ),
+      sha: exactSha(value.source?.sha, "source.sha"),
+      treeSha: exactSha(value.source?.treeSha, "source.treeSha"),
+    },
+    runtime: {
+      repository: repository(value.runtime?.repository, "runtime.repository"),
+      sha: exactSha(value.runtime?.sha, "runtime.sha"),
+    },
+    platform: {
+      id: required(value.platform?.id, "platform.id"),
+      name: required(value.platform?.name, "platform.name"),
+    },
+    request: {
+      count: requestCount,
+      artifact:
+        requestCount > 0
+          ? required(value.request?.artifact, "request.artifact")
+          : optional(value.request?.artifact, "request.artifact"),
+    },
+    authority: {
+      runId:
+        requestCount > 0
+          ? required(value.authority?.runId, "authority.runId")
+          : optional(value.authority?.runId, "authority.runId"),
+      resultArtifact:
+        requestCount > 0
+          ? required(
+              value.authority?.resultArtifact,
+              "authority.resultArtifact",
+            )
+          : optional(
+              value.authority?.resultArtifact,
+              "authority.resultArtifact",
+            ),
+    },
+    artifact: {
+      name: required(value.artifact?.name, "artifact.name"),
+      manifestArtifact: required(
+        value.artifact?.manifestArtifact,
+        "artifact.manifestArtifact",
+      ),
+      diagnosticsArtifact: required(
+        value.artifact?.diagnosticsArtifact,
+        "artifact.diagnosticsArtifact",
+      ),
+    },
+    workingDirectory: safeRelativePath(
+      value.workingDirectory || ".",
+      "workingDirectory",
+    ),
+  };
+  if (
+    requestCount === 0 &&
+    (delegation.authority.runId || delegation.authority.resultArtifact)
+  ) {
+    throw new Error(
+      "unsigned delegation must not contain authority result coordinates",
+    );
+  }
+  return delegation;
+}
+
+export function createArtifactSigningDelegation({
+  sourceRepository = process.env.GITHUB_REPOSITORY,
+  sourceRunId = process.env.GITHUB_RUN_ID,
+  sourceRunAttempt = process.env.GITHUB_RUN_ATTEMPT || "1",
+  sourceSha = process.env.BUILDCHAIN_SOURCE_SHA,
+  sourceTreeSha = process.env.BUILDCHAIN_SOURCE_TREE_SHA,
+  runtimeRepository = process.env.BUILDCHAIN_RUNTIME_REPOSITORY,
+  runtimeSha = process.env.BUILDCHAIN_RUNTIME_SHA,
+  platformId = process.env.BUILDCHAIN_PLATFORM_ID,
+  platformName = process.env.BUILDCHAIN_PLATFORM_NAME,
+  requestCount = process.env.BUILDCHAIN_SIGNING_REQUEST_COUNT || "0",
+  requestArtifact = process.env.BUILDCHAIN_SIGNING_REQUEST_ARTIFACT || "",
+  authorityRunId = process.env.BUILDCHAIN_AUTHORITY_RUN_ID || "",
+  resultArtifact = process.env.BUILDCHAIN_SIGNING_RESULT_ARTIFACT || "",
+  artifactName = process.env.BUILDCHAIN_ARTIFACT_NAME,
+  manifestArtifact = process.env.BUILDCHAIN_MANIFEST_ARTIFACT_NAME,
+  diagnosticsArtifact = process.env.BUILDCHAIN_DIAGNOSTICS_ARTIFACT_NAME,
+  workingDirectory = process.env.BUILDCHAIN_SIGNING_CWD || ".",
+} = {}) {
+  return validateArtifactSigningDelegation({
+    schemaVersion: 1,
+    contract: CONTRACT,
+    source: {
+      repository: sourceRepository,
+      runId: sourceRunId,
+      runAttempt: Number(sourceRunAttempt),
+      sha: sourceSha,
+      treeSha: sourceTreeSha,
+    },
+    runtime: { repository: runtimeRepository, sha: runtimeSha },
+    platform: { id: platformId, name: platformName },
+    request: { count: Number(requestCount), artifact: requestArtifact },
+    authority: { runId: authorityRunId, resultArtifact },
+    artifact: { name: artifactName, manifestArtifact, diagnosticsArtifact },
+    workingDirectory,
+  });
+}
+
+export function sealArtifactSigningDelegation({
+  outputPath = process.env.BUILDCHAIN_SIGNING_DELEGATION_PATH,
+  ...values
+} = {}) {
+  const delegation = createArtifactSigningDelegation(values);
+  const target = path.resolve(required(outputPath, "delegation output path"));
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, `${JSON.stringify(delegation, null, 2)}\n`);
+  return delegation;
+}
+
+export function readArtifactSigningDelegation(
+  inputPath = process.env.BUILDCHAIN_SIGNING_DELEGATION_PATH,
+) {
+  const target = path.resolve(required(inputPath, "delegation input path"));
+  return validateArtifactSigningDelegation(
+    JSON.parse(fs.readFileSync(target, "utf8")),
+  );
+}
+
+export function artifactSigningDelegationOutputs(delegation) {
+  const value = validateArtifactSigningDelegation(delegation);
+  return {
+    "request-count": String(value.request.count),
+    "request-artifact": value.request.artifact,
+    "authority-run-id": value.authority.runId,
+    "result-artifact": value.authority.resultArtifact,
+    "artifact-name": value.artifact.name,
+    "manifest-artifact-name": value.artifact.manifestArtifact,
+    "diagnostics-artifact-name": value.artifact.diagnosticsArtifact,
+    "working-directory": value.workingDirectory,
+  };
+}
+
+export function assertArtifactSigningDelegationContext(
+  delegation,
+  {
+    sourceRepository = process.env.BUILDCHAIN_EXPECTED_SOURCE_REPOSITORY || "",
+    sourceRunId = process.env.BUILDCHAIN_EXPECTED_SOURCE_RUN_ID || "",
+    sourceRunAttempt = process.env.BUILDCHAIN_EXPECTED_SOURCE_RUN_ATTEMPT || "",
+    sourceSha = process.env.BUILDCHAIN_EXPECTED_SOURCE_SHA || "",
+    runtimeRepository = process.env.BUILDCHAIN_EXPECTED_RUNTIME_REPOSITORY ||
+      "",
+    runtimeSha = process.env.BUILDCHAIN_EXPECTED_RUNTIME_SHA || "",
+    platformId = process.env.BUILDCHAIN_EXPECTED_PLATFORM_ID || "",
+  } = {},
+) {
+  const value = validateArtifactSigningDelegation(delegation);
+  const expectations = [
+    [sourceRepository, value.source.repository, "source repository"],
+    [sourceRunId, value.source.runId, "source run ID"],
+    [sourceRunAttempt, String(value.source.runAttempt), "source run attempt"],
+    [sourceSha, value.source.sha, "source SHA"],
+    [runtimeRepository, value.runtime.repository, "runtime repository"],
+    [runtimeSha, value.runtime.sha, "runtime SHA"],
+    [platformId, value.platform.id, "platform ID"],
+  ];
+  for (const [expected, actual, label] of expectations) {
+    if (expected && String(expected) !== actual)
+      throw new Error(`artifact signing delegation ${label} mismatch`);
+  }
+  return value;
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const mode = process.argv[2] || "seal";
+    if (mode === "seal") {
+      sealArtifactSigningDelegation();
+    } else if (mode === "outputs") {
+      const delegation = assertArtifactSigningDelegationContext(
+        readArtifactSigningDelegation(),
+      );
+      writeGitHubOutputs(artifactSigningDelegationOutputs(delegation));
+    } else {
+      throw new Error(`unsupported artifact signing delegation mode: ${mode}`);
+    }
+  } catch (error) {
+    console.error(
+      `::error::${String(error?.message || error).replace(/\r?\n/gu, "%0A")}`,
+    );
+    process.exitCode = 1;
+  }
+}

package/scripts/audit-github-governance.mjs

@@ -254,15 +254,33 @@ function addMinutes(iso, minutes) {
   return new Date(Date.parse(iso) + minutes * 60_000).toISOString();
 }
 
-function repositorySelector(repositories, requested) {
-  if (!requested) return repositories;
-  const exact = repositories.filter((repository) =>
-    repository.full_name === requested ||
-    repository.name === requested);
-  if (exact.length !== 1) {
-    throw new Error(`repository selector must resolve exactly once: ${requested}`);
+function repositoryVisibility(repository) {
+  return String(
+    repository.visibility || (repository.private ? "private" : "public"),
+  ).toLowerCase();
+}
+
+export function selectGithubGovernanceRepositories(
+  repositories,
+  requested = "",
+  descriptor = BUILDCHAIN_GITHUB_GOVERNANCE_AUTHORITY,
+) {
+  const exact = requested
+    ? repositories.filter((repository) =>
+        repository.full_name === requested || repository.name === requested)
+    : repositories;
+  if (requested && exact.length !== 1) {
+    throw new Error("repository selector must resolve exactly once");
   }
-  return exact;
+  const managedVisibilities = new Set(
+    descriptor.repositoryAdmission.managedVisibilities || ["public"],
+  );
+  const selected = exact.filter((repository) =>
+    managedVisibilities.has(repositoryVisibility(repository)));
+  if (requested && selected.length !== 1) {
+    throw new Error("repository selector is outside managed governance scope");
+  }
+  return selected;
 }
 
 export function collectGithubGovernanceAudit({
@@ -291,7 +309,10 @@ export function collectGithubGovernanceAudit({
   if (!organizationState.ok || !repositoriesState.readable) {
     throw new Error("organization or managed repository inventory is unreadable; governance audit fails closed");
   }
-  const selected = repositorySelector(repositoriesState.repositories, repository);
+  const selected = selectGithubGovernanceRepositories(
+    repositoriesState.repositories,
+    repository,
+  );
   if (targetRef && selected.length !== 1) {
     throw new Error("--target-ref requires exactly one selected repository");
   }
@@ -316,9 +337,7 @@ export function collectGithubGovernanceAudit({
   const diagnostics = [];
   for (const metadata of selected) {
     const fullName = String(metadata.full_name || "");
-    const visibilityClass = String(
-      metadata.visibility || (metadata.private ? "private" : "public"),
-    );
+    const visibilityClass = repositoryVisibility(metadata);
     const repositoryIdentityRoot = githubRepositoryIdentityRoot({
       provider: "github",
       providerRepositoryId: String(metadata.node_id || metadata.id || ""),
@@ -420,7 +439,7 @@ export function collectGithubGovernanceAudit({
     }
   }
   const visibility = selected.reduce((counts, item) => {
-    const key = String(item.visibility || (item.private ? "private" : "public"));
+    const key = repositoryVisibility(item);
     counts[key] = Number(counts[key] || 0) + 1;
     return counts;
   }, {});

package/scripts/audit-publication-control-plane.mjs

@@ -6,6 +6,7 @@ import path from "node:path";
 import {
   evaluateBuildchainReleaseReconciliation,
   evaluatePublicationControlPlaneSnapshot,
+  matchesGithubDeploymentPolicy,
 } from "../packages/core/publication-control-plane-audit.js";
 
 function flag(name, fallback = "") {
@@ -197,8 +198,10 @@ function main() {
   const requiredStatusCheck = flag("required-status-check", "check");
   const jobId = flag("job", "promote");
   const environment = flag("environment", "none");
-  const providerEnvironment = environment === "none" ? "" : environment;
   const branch = flag("branch");
+  const environmentRef = flag("environment-ref", branch);
+  const environmentRefType = flag("environment-ref-type", "branch");
+  const providerEnvironment = environment === "none" ? "" : environment;
   const sourceSha = flag("source-sha").toLowerCase();
   const packageName = flag("package", "@kungfu-tech/buildchain");
   const publisherMode = flag("publisher-mode", "npm-trusted-publisher");
@@ -239,15 +242,19 @@ function main() {
   const deploymentBranches = environment !== "none" && environmentState.deployment_branch_policy?.custom_branch_policies === true
     ? githubJson(`repos/${repository}/environments/${encodeURIComponent(environment)}/deployment-branch-policies?per_page=100`, "Environment deployment branch policy")
     : { branch_policies: [] };
-  const exactEnvironmentBranchPolicy = (deploymentBranches.branch_policies || []).find((entry) =>
-    entry?.type === "branch" && entry?.name === branch
+  if (!["branch", "tag"].includes(environmentRefType)) {
+    throw new Error(`unsupported --environment-ref-type: ${environmentRefType}`);
+  }
+  const matchingEnvironmentPolicy = (deploymentBranches.branch_policies || []).find((entry) =>
+    matchesGithubDeploymentPolicy(entry, { ref: environmentRef, refType: environmentRefType })
   );
   const environmentBranchAuthorized = environment !== "none" && (
     (
+      environmentRefType === "branch" &&
       environmentState.deployment_branch_policy?.protected_branches === true &&
       branchState.protected === true
     ) ||
-    Boolean(exactEnvironmentBranchPolicy)
+    Boolean(matchingEnvironmentPolicy)
   );
   const oidc = githubJson(`repos/${repository}/actions/oidc/customization/sub`, "OIDC subject policy");
   if (!["npm-trusted-publisher", "github-token", "oidc-role"].includes(publisherMode)) {
@@ -465,12 +472,14 @@ function main() {
           environmentState.deployment_branch_policy?.protected_branches === true ||
           (deploymentBranches.branch_policies || []).length > 0,
         branchAuthorized: environmentBranchAuthorized,
-        branchPolicyMode: environmentState.deployment_branch_policy?.protected_branches === true
+        branchPolicyMode: environmentRefType === "branch" && environmentState.deployment_branch_policy?.protected_branches === true
           ? "protected-branches"
-          : exactEnvironmentBranchPolicy
-            ? "exact-custom-branch"
+          : matchingEnvironmentPolicy
+            ? `custom-${environmentRefType}-policy`
             : "unqualified",
-        authorizedBranch: exactEnvironmentBranchPolicy?.name || "",
+        authorizedBranch: matchingEnvironmentPolicy?.name || "",
+        authorizedRef: environmentRef,
+        authorizedRefType: environmentRefType,
         reviewRequired: reviewRules.length > 0,
         preventSelfReview: reviewRules.some((rule) => rule.prevent_self_review === true),
       },