fix(ci): immutable_build가 gate 로그와 advisory 기록을 항상 올린다

문제: ci:gate는 명령 출력을 artifacts/quality/gates/FE-GATE-<NNN>.txt에만
쓰고 콘솔에는 PASS/FAIL 한 줄만 남긴다(scripts/run-ci-gate.ts). release
단계 job immutable_build는 후보 tar만, 그것도 성공했을 때만 올린다. 그래서
실제 run에서 FE-GATE-015·027이 왜 실패했는지와 FE-GATE-027이 쓰는
artifacts/security/dependency-advisories.json(1103/13-03의 신호)이 runner
작업 디렉터리와 함께 사라진다. 다른 gate job은 artifacts/를 if: always()로
올린다.

고른 방법:
- config/ci/gates.json의 immutable_build 마지막에 upload 단계를 더한다.
  transfer ID는 immutable-gate-evidence, 이름은
  immutable-gate-evidence-<run>-<attempt>, always: true. 대상은
  FE-GATE-015·027의 log와 evidence 산출물(gate 순서)과 advisory 기록 7개다.
  FE-GATE-015의 verification.json 등은 후보가 만들어지지 않으면 후보 안에도
  없으므로 같이 올린다.
- 계약(scripts/contracts/ci-gates.ts)이 이 단계를 고정한다. immutable_build의
  단계 목록에 upload 하나가 늘고, 이 upload가 always이고 마지막 단계이며
  경로가 "job이 도는 gate의 log·evidence 경로 + advisory 기록"과 같아야
  한다. 경로는 계약의 artifact 등록에서 계산하므로 log 경로가 바뀌면 함께
  따라온다. advisory 기록은 gate evidence가 아니라(막지 않는 신호) 경로를
  scripts/lib/dependency-advisories.ts의 상수로 옮기고 scan 스크립트도 그
  상수를 쓴다.
- 후보 archive의 member set, 후보 upload(always 없음), 하위 job의 download는
  그대로다. 생성 workflow를 generator 출력과 같게 손으로 고쳤다.

버린 대안:
- immutable_build도 artifacts/ 전체를 올림: 다른 job과 같지만 후보 증거가
  두 이름으로 나가 어느 것이 승격 대상인지 흐려진다. 필요한 파일만 고정했다.
- ci:gate가 실패한 명령의 마지막 N줄을 콘솔에 씀(리뷰 대안 c, d의 콘솔
  한 줄 포함): 모든 job에 걸리고 provider 출력의 비밀 노출과 로그 상한을
  다시 따져야 한다. 담당 지시 범위(업로드) 밖이라 이번에 하지 않았다.

위험·한계:
- checkout·install 단계에서 실패하면 올릴 파일이 없어 이 단계도
  if-no-files-found: error로 실패한다. job은 이미 실패한 뒤라 결과는 같다.
  merge·release job의 upload도 같은 동작이다.
- 실제 Gitea runner에서 stage=release를 돌려 산출물이 남는지는 확인하지
  못했다(runner 없음). 확인한 것은 계약·생성 workflow까지다.
- 콘솔에는 여전히 한 줄만 나온다. 사람이 산출물을 열어야 이유를 본다.

검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/ci-workflow-generation.test.ts
- corepack pnpm check:ci, check:types, lint, verify:documentation

Refs: 1105/13-01, 1103/13-03
This commit is contained in:
DongHyeonka
2026-11-05 22:12:30 +09:00
parent 9655958bda
commit 629c713ce4
8 changed files with 210 additions and 5 deletions
+14
View File
@@ -207,6 +207,20 @@ jobs:
name: "release-candidate-${{ gitea.run_id }}-${{ gitea.run_attempt }}"
path: ".release/release-candidate-${{ gitea.run_id }}-${{ gitea.run_attempt }}.tar.gz"
if-no-files-found: error
- name: Upload immutable gate evidence
if: always()
uses: https://github.com/ChristopherHX/gitea-upload-artifact@81f940d004763f986ba3582c007fd842dd5cb0d7
with:
name: "immutable-gate-evidence-${{ gitea.run_id }}-${{ gitea.run_attempt }}"
path: |
artifacts/quality/gates/FE-GATE-015.txt
artifacts/release/release-candidate.json
artifacts/release/verification.json
artifacts/security/supply-chain-coherence.json
artifacts/quality/gates/FE-GATE-027.txt
artifacts/release/deployment-admission.json
artifacts/security/dependency-advisories.json
if-no-files-found: error
vulnerability_provider:
name: external-vulnerability-provider
+15
View File
@@ -2508,6 +2508,21 @@
"paths": [
".release/release-candidate-${{ gitea.run_id }}-${{ gitea.run_attempt }}.tar.gz"
]
},
{
"kind": "upload",
"transferId": "immutable-gate-evidence",
"name": "immutable-gate-evidence-${{ gitea.run_id }}-${{ gitea.run_attempt }}",
"paths": [
"artifacts/quality/gates/FE-GATE-015.txt",
"artifacts/release/release-candidate.json",
"artifacts/release/verification.json",
"artifacts/security/supply-chain-coherence.json",
"artifacts/quality/gates/FE-GATE-027.txt",
"artifacts/release/deployment-admission.json",
"artifacts/security/dependency-advisories.json"
],
"always": true
}
]
},
+11 -1
View File
@@ -163,7 +163,12 @@ Release tier의 `immutable_build`는 `dist`의 hidden `.vite` entries, raw
번 생성해 run ID/attempt로 구분된 archive로 게시한다. Raw lock bytes의 SHA-256은
dependency inventory와 candidate manifest 양쪽의 `lockfileSha256`과 같아야 한다.
Producer는 게시 전에 manifest가 선언한 exact member set과 각 byte digest를
검증하고 archive SHA-256을 job output으로 고정한다. Vulnerability/provenance
검증하고 archive SHA-256을 job output으로 고정한다. 같은 job은 마지막 단계에서
FE-GATE-015·027의 gate log와 evidence, `scan:dependency-advisories` 기록을 후보와
다른 이름(`immutable-gate-evidence-<run>-<attempt>`)으로 성공·실패와 상관없이
올린다(1105/13-01). `ci:gate`는 명령 출력을 gate log에만 쓰고 콘솔에는 한 줄만
남기므로, release 단계의 실패 이유는 이 산출물에서 읽는다. 후보 archive의 member
set은 그대로다. Vulnerability/provenance
provider job은 같은 archive를 각각 내려받아 output SHA-256과 exact member set을
확인한 뒤 checkout과 분리된 root에만 추출하고, `CANDIDATE_LOCKFILE_PATH`와
`CANDIDATE_DIST_SHA256`를 외부 command에 전달한다. Provider command 실행 후에는
@@ -525,6 +530,11 @@ Repository variables required by higher tiers:
findings) or `UNVERIFIED` (no registry). It never fails the gate, because an
advisory database that changes under unchanged code would break releases;
the signed verdict of the vulnerability provider still decides promotion.
The job console shows only one PASS/FAIL line per gate, so the
immutable_build job uploads both gates' logs and evidence and this record as
the run artifact `immutable-gate-evidence-<run>-<attempt>`, whether the job
passed or failed (1105/13-01). Read why FE-GATE-015 or FE-GATE-027 failed,
and the advisory status, there.
`renovate.json` opens security update PRs once a Renovate runner is attached;
a dependency update re-approves the dependency baseline in the same change
(`update:dependency-baseline`).
+45 -1
View File
@@ -4,6 +4,7 @@ import path from "node:path";
import { z } from "zod";
import { DEPENDENCY_ADVISORIES_RECORD_PATH } from "../lib/dependency-advisories.ts";
import { PROMOTION_FORMULA } from "../lib/promotion-readiness.ts";
import {
RELEASE_CANDIDATE_EVIDENCE_PATHS,
@@ -952,7 +953,7 @@ function validateContractSemantics(
const expectedStepKinds: Readonly<Record<string, readonly CiWorkflowStep["kind"][]>> = {
merge_gate: ["checkout", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"],
release_gate: ["checkout", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"],
immutable_build: ["checkout", "setup-node", "frozen-install", "run-gate", "archive-candidate", "upload"],
immutable_build: ["checkout", "setup-node", "frozen-install", "run-gate", "archive-candidate", "upload", "upload"],
vulnerability_provider: ["checkout", "setup-node", "frozen-install", "download", "run-provider", "validate-provider-evidence", "upload"],
provenance_provider: ["checkout", "setup-node", "frozen-install", "download", "run-provider", "validate-provider-evidence", "upload"],
promotion: ["checkout", "setup-node", "frozen-install", "download", "download", "download", "verify-promotion", "upload", "cleanup-promotion"],
@@ -1150,6 +1151,29 @@ function validateContractSemantics(
validateCanonicalStepFields(contract, issue);
}
const IMMUTABLE_GATE_EVIDENCE_TRANSFER_ID = "immutable-gate-evidence";
/**
* 1105/13-01. What immutable_build uploads besides the candidate: the log and
* evidence artifacts of each gate it runs, in gate order, then the advisory
* record of scan:dependency-advisories (FE-GATE-027), which is not a gate
* evidence artifact because it never blocks.
*/
function immutableGateEvidencePaths(
contract: Pick<z.infer<typeof ciGateContractBaseSchema>, "artifacts" | "gates">,
immutable: Pick<z.infer<typeof jobSchema>, "gateIds">,
): string[] {
const paths = immutable.gateIds.flatMap((gateId) => {
const gate = contract.gates.find(({ id }) => id === gateId);
return gate
? [gate.logArtifactId, ...gate.evidenceArtifactIds].flatMap((artifactId) =>
contract.artifacts.filter(({ id }) => id === artifactId).map(({ path: artifactPath }) => artifactPath),
)
: [];
});
return [...new Set([...paths, DEPENDENCY_ADVISORIES_RECORD_PATH])];
}
function validateCanonicalStepFields(
contract: z.infer<typeof ciGateContractBaseSchema>,
issue: (message: string, path?: PropertyKey[]) => void,
@@ -1168,6 +1192,26 @@ function validateCanonicalStepFields(
) {
issue("immutable archive and upload fields must remain linked");
}
// 1105/13-01. ci:gate writes command output only to the gate log and prints
// one PASS/FAIL line, and this job uploaded only the candidate, on success.
// Why FE-GATE-015 or FE-GATE-027 failed, and the advisory record FE-GATE-027
// writes, went with the runner's workspace. A separate transfer, always and
// last, carries them; the candidate archive's member set stays as it is.
const gateEvidence = immutable?.steps.find(
(step) => step.kind === "upload" && step.transferId === IMMUTABLE_GATE_EVIDENCE_TRANSFER_ID,
);
if (
!immutable ||
gateEvidence?.kind !== "upload" ||
gateEvidence.always !== true ||
immutable.steps.at(-1) !== gateEvidence ||
JSON.stringify(gateEvidence.paths) !== JSON.stringify(immutableGateEvidencePaths(contract, immutable))
) {
issue(
"immutable_build must upload its gates' logs and evidence and the dependency advisory record " +
`as ${IMMUTABLE_GATE_EVIDENCE_TRANSFER_ID}, with always, as its last step`,
);
}
const providerExpectations = {
vulnerability_provider: {
+6
View File
@@ -1,5 +1,11 @@
import { validateVulnerabilityReport } from "./supply-chain.ts";
/**
* Where scan:dependency-advisories writes its record. 1105/13-01: the
* immutable_build job uploads it on every outcome (scripts/contracts/ci-gates.ts).
*/
export const DEPENDENCY_ADVISORIES_RECORD_PATH = "artifacts/security/dependency-advisories.json";
/**
* 1103/13-03. The vulnerability verdict belongs to the external provider of
* the production promotion (signed, independent of the build). Without a
+5 -2
View File
@@ -2,7 +2,10 @@ import { spawnSync } from "node:child_process";
import { createHash } from "node:crypto";
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { summarizeDependencyAdvisories } from "./lib/dependency-advisories.ts";
import {
DEPENDENCY_ADVISORIES_RECORD_PATH,
summarizeDependencyAdvisories,
} from "./lib/dependency-advisories.ts";
/**
* 1103/13-03. Release-stage signal for known dependency advisories
@@ -17,7 +20,7 @@ import { summarizeDependencyAdvisories } from "./lib/dependency-advisories.ts";
* result is UNVERIFIED, not PASS. The signed verdict of the vulnerability
* provider stays the only one that decides a promotion.
*/
const RECORD_PATH = "artifacts/security/dependency-advisories.json";
const RECORD_PATH = DEPENDENCY_ADVISORIES_RECORD_PATH;
const [policy, exceptions, lockfile] = await Promise.all([
readFile("config/security/vulnerability-policy.json", "utf8").then((text) => JSON.parse(text) as Record<string, unknown>),
@@ -210,6 +210,20 @@ jobs:
name: "release-candidate-\${{ gitea.run_id }}-\${{ gitea.run_attempt }}"
path: ".release/release-candidate-\${{ gitea.run_id }}-\${{ gitea.run_attempt }}.tar.gz"
if-no-files-found: error
- name: Upload immutable gate evidence
if: always()
uses: https://github.com/ChristopherHX/gitea-upload-artifact@81f940d004763f986ba3582c007fd842dd5cb0d7
with:
name: "immutable-gate-evidence-\${{ gitea.run_id }}-\${{ gitea.run_attempt }}"
path: |
artifacts/quality/gates/FE-GATE-015.txt
artifacts/release/release-candidate.json
artifacts/release/verification.json
artifacts/security/supply-chain-coherence.json
artifacts/quality/gates/FE-GATE-027.txt
artifacts/release/deployment-admission.json
artifacts/security/dependency-advisories.json
if-no-files-found: error
vulnerability_provider:
name: external-vulnerability-provider
+100 -1
View File
@@ -1654,7 +1654,7 @@ describe("CI workflow generation", () => {
'if [ -n "$PROMOTION_STAGING_ROOT" ] && [ -n "$PROMOTION_CLEANUP_TOKEN" ] && [ -n "$PROMOTION_RUNNER_TEMP_DEV" ] && [ -n "$PROMOTION_RUNNER_TEMP_INO" ] && [ -n "$PROMOTION_STAGING_DEV" ] && [ -n "$PROMOTION_STAGING_INO" ]; then',
);
const actionUses = [...first.matchAll(/^\s+-?\s*uses: (.+)$/gmu)].map((match) => match[1]);
expect(actionUses).toHaveLength(33);
expect(actionUses).toHaveLength(34);
expect(new Set(actionUses)).toEqual(
new Set([
"https://github.com/actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5",
@@ -1743,6 +1743,105 @@ describe("CI workflow generation", () => {
expect(workflowGateExecutionFailures(contract, workflow)).toEqual([]);
});
// 1105/13-01. ci:gate writes each command's output only to the gate log and
// prints one PASS/FAIL line. immutable_build uploaded only the candidate, on
// success, so why FE-GATE-015 or FE-GATE-027 failed, and the advisory record
// FE-GATE-027 writes (1103/13-03), went with the runner's workspace.
const IMMUTABLE_GATE_EVIDENCE_PATHS = [
"artifacts/quality/gates/FE-GATE-015.txt",
"artifacts/release/release-candidate.json",
"artifacts/release/verification.json",
"artifacts/security/supply-chain-coherence.json",
"artifacts/quality/gates/FE-GATE-027.txt",
"artifacts/release/deployment-admission.json",
"artifacts/security/dependency-advisories.json",
];
it("uploads immutable_build's gate logs, evidence and advisory record on every outcome (1105/13-01)", async () => {
const contract = await loadCiGateContract(process.cwd());
const index = indexCiGateContract(contract);
const gatePaths = ["FE-GATE-015", "FE-GATE-027"].flatMap((gateId) => {
const gate = index.gates.get(gateId)!;
return [gate.logArtifactId, ...gate.evidenceArtifactIds].map((artifactId) => index.artifacts.get(artifactId)!.path);
});
expect(IMMUTABLE_GATE_EVIDENCE_PATHS).toEqual([...gatePaths, "artifacts/security/dependency-advisories.json"]);
const workflow = renderCiWorkflow(contract);
const immutable = workflow.slice(
workflow.indexOf(" immutable_build:\n"),
workflow.indexOf(" vulnerability_provider:\n"),
);
const candidateUpload = immutable.indexOf(" - name: Upload release candidate\n");
const evidenceUpload = immutable.indexOf(" - name: Upload immutable gate evidence\n");
expect(candidateUpload).toBeGreaterThan(immutable.indexOf("ci:gate -- FE-GATE-027"));
expect(evidenceUpload).toBeGreaterThan(candidateUpload);
expect(immutable.slice(evidenceUpload)).toBe(
[
" - name: Upload immutable gate evidence",
" if: always()",
` uses: ${resolveCiActionUses("uploadArtifact")}`,
" with:",
' name: "immutable-gate-evidence-${{ gitea.run_id }}-${{ gitea.run_attempt }}"',
" path: |",
...IMMUTABLE_GATE_EVIDENCE_PATHS.map((target) => ` ${target}`),
" if-no-files-found: error",
"",
"",
].join("\n"),
);
// The candidate still goes up only after its archive was validated, and
// the archive's member set is not widened by the evidence.
expect(immutable.slice(candidateUpload, evidenceUpload)).not.toContain("if: always()");
const archive = contract.jobs
.find(({ id }) => id === "immutable_build")
?.steps.find((step) => step.kind === "archive-candidate");
expect(archive?.kind === "archive-candidate" ? archive.members : []).not.toContain(
"artifacts/quality/gates/FE-GATE-027.txt",
);
});
it.each([
[
"is missing",
(steps: Record<string, any>[]) => steps.splice(steps.findIndex((step) => step.transferId === "immutable-gate-evidence"), 1),
],
[
"runs only on success",
(steps: Record<string, any>[]) => delete steps.find((step) => step.transferId === "immutable-gate-evidence")!.always,
],
[
"leaves out the advisory record",
(steps: Record<string, any>[]) => {
const upload = steps.find((step) => step.transferId === "immutable-gate-evidence")!;
upload.paths = upload.paths.filter((target: string) => target !== "artifacts/security/dependency-advisories.json");
},
],
[
"leaves out the FE-GATE-027 log",
(steps: Record<string, any>[]) => {
const upload = steps.find((step) => step.transferId === "immutable-gate-evidence")!;
upload.paths = upload.paths.filter((target: string) => target !== "artifacts/quality/gates/FE-GATE-027.txt");
},
],
[
"comes before the candidate upload",
(steps: Record<string, any>[]) => {
const evidence = steps.splice(steps.findIndex((step) => step.transferId === "immutable-gate-evidence"), 1)[0]!;
steps.splice(steps.findIndex((step) => step.transferId === "release-candidate"), 0, evidence);
},
],
])("rejects an immutable_build whose gate evidence upload %s (1105/13-01)", async (_name, mutate) => {
const contract = JSON.parse(
JSON.stringify(await loadCiGateContract(process.cwd())),
) as Record<string, any>;
const steps = contract.jobs.find((job: Record<string, any>) => job.id === "immutable_build").steps;
expect(steps.filter((step: Record<string, any>) => step.transferId === "immutable-gate-evidence")).toHaveLength(1);
mutate(steps);
expect(() => parseCiGateContract(contract)).toThrow(
/immutable_build must upload its gates' logs and evidence and the dependency advisory record/u,
);
});
it.each([
["a non-matrix gate step", " run: corepack pnpm ci:gate -- FE-GATE-027\n", "FE-GATE-027"],
["a matrix entry", " - { gate: FE-GATE-020, name: removability, browser: false }\n", "FE-GATE-020"],