feat(ci): 제품이 배포 job과 merge 검사를 제품 소유 overlay에 적는다
문제: 배포 슬롯을 채우거나 제품 전용 merge 검사를 더하려면 템플릿 소유 config/ci/gates.json(약 3,000줄)과 생성 workflow를 고쳐야 했다. 문서도 "deployment job을 gates.json에서 고치라"고 적었다. 템플릿 gates.json이 바뀔 때마다 제품은 큰 JSON과 생성 YAML의 충돌을 손으로 풀어야 했고, 다운스트림 tech-log는 이미 제품 커밋 3개에서 gates.json을 고쳤다. 고른 방법: 제품 소유 config/ci/product-gates.json을 둔다. 템플릿은 빈 파일로 싣고 고치지 않는다. 담을 수 있는 것은 둘뿐이다. - deployment: deploy package script와 vars.*·secrets.* 바인딩. 나머지 슬롯(promoted-release download, digest로 확인하는 extract, deploy)은 템플릿이 렌더링하고, 채운 계약을 다시 parse해 슬롯 규칙(앞 커밋)을 그대로 적용한다. secret은 deploy 단계에만 간다. gates.json과 overlay 양쪽에서 슬롯을 채우면 거절한다. - mergeGates: PRODUCT-GATE-NNN id의 package script. 템플릿 job 뒤의 product_merge_gate job이 merge와 같은 조건에서 matrix로 돈다. FE-GATE id·명령·산출물·readiness 공식은 건드리지 못한다. loadCiGateContract와 생성기, check:ci가 두 파일을 함께 읽고, 계약 기준선(contract-baseline.json)은 템플릿 계약만 센다. 없는 script는 거절하고, 제품 gate script는 ungated 검사에서 gated로 센다. 버린 대안: 저장소 변수로 배포 명령만 받기(제품 게이트를 못 풀고 실행할 명령이 저장소 밖에 숨는다), 제품 전용 workflow 파일(Gitea에서 run 사이 산출물 전달이 검증되지 않았다). 위험·한계: 제품 gate는 ci:gate의 로그·증거 산출물과 readiness 공식 밖이다. merge를 막으려면 제품이 그 job을 필수 검사로 지정한다. 생성 workflow는 여전히 커밋되는 파일이라, 템플릿 변경과 같은 줄을 건드리면 재생성이 필요하다. 실제 Gitea runner에서는 돌리지 않았다. 검증: tests/unit/product-ci-overlay.test.ts 11건(빈 overlay, 슬롯 채우기와 기준선 유지, 양쪽 채우기 거절, 없는 script 거절, 제품 job 렌더링과 실행 확인, 스키마 거절 6건). 작업 트리에서 overlay와 script를 채워 generate:ci-workflow → check:ci PASS, CI workflow bytes PASS, 생성 YAML 파싱 확인 후 되돌렸다. 그 상태의 workflow와 gates.json에 템플릿 변경(게이트 이름 2개)을 diff3로 3-way 병합하면 충돌 0이다. ci-workflow-generation 425건, check:ci PASS. Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-07
This commit is contained in:
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"deployment": null,
|
||||
"mergeGates": []
|
||||
}
|
||||
@@ -107,6 +107,7 @@ release admission refused for staging:
|
||||
- `src/contracts/product-contracts.ts`: 제품 인증 프로필이나 제품 런타임 설정 키가 필요할 때.
|
||||
- 템플릿 파일 `src/contracts/rest-profiles.ts`는 고치지 않는다.
|
||||
- `config/runtime/<profile>.json`: 환경별로 기능을 끄고 싶을 때(`FEATURE_OVERRIDES`).
|
||||
- `config/ci/product-gates.json`: 배포 job(`deployment`)을 채우거나 제품 전용 merge 검사(`PRODUCT-GATE-NNN`)를 더할 때. 템플릿 파일 `config/ci/gates.json`은 고치지 않는다. 형식은 [`ci-quality-gates.md`](../operations/ci-quality-gates.md)에 있다.
|
||||
- `package.json`, lockfile, `config/security/dependency-change-evidence.json`: 계약 패키지를 더할 때(B절).
|
||||
|
||||
정본 표에 없는 것:
|
||||
|
||||
@@ -342,9 +342,44 @@ name the candidate's entry script (1103/13-01). The workflow deploys
|
||||
nothing itself. Between `promotion` and `production_gate` sits the `deployment`
|
||||
job, the project's deployment slot. It is empty by default: it reports
|
||||
`deployed=false`, FE-GATE-019 does not probe the host and ends `UNVERIFIED`
|
||||
(exit 3), and the production stage stays open. To fill it, edit the
|
||||
`deployment` job in `config/ci/gates.json` and run `corepack pnpm
|
||||
generate:ci-workflow`. The contract allows the steps `checkout`, `setup-node`,
|
||||
(exit 3), and the production stage stays open. To fill it, set `deployment`
|
||||
in the product-owned `config/ci/product-gates.json` and run `corepack pnpm
|
||||
generate:ci-workflow` (1103/12-07):
|
||||
|
||||
```json
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"deployment": {
|
||||
"script": "deploy:desktop",
|
||||
"environment": [
|
||||
{ "name": "DEPLOY_HOST", "value": "${{ vars.DEPLOY_HOST }}" },
|
||||
{ "name": "DEPLOY_SSH_KEY", "value": "${{ secrets.DEPLOY_SSH_KEY }}" }
|
||||
]
|
||||
},
|
||||
"mergeGates": []
|
||||
}
|
||||
```
|
||||
|
||||
The template renders the rest of the slot: it downloads the `promoted-release`
|
||||
transfer, extracts it to `.release/promoted-release` against the candidate
|
||||
digest, then runs the script, which deploys `.release/promoted-release/dist`.
|
||||
`environment` takes only `vars.*` and `secrets.*` values. The template ships
|
||||
this file empty and never changes it, so a template sync does not meet it;
|
||||
`config/ci/gates.json` stays the template's, and its contract baseline counts
|
||||
the template contract only. A slot filled in both files is refused.
|
||||
|
||||
`mergeGates` adds the product's own checks, such as a contract check against
|
||||
the paired backend: `{ "id": "PRODUCT-GATE-001", "name": "backend-contract",
|
||||
"script": "check:backend-contract" }`. Ids are `PRODUCT-GATE-NNN`; the
|
||||
`FE-GATE-NNN` ids, their commands, artifacts and readiness formula stay the
|
||||
template's. Each runs as `corepack pnpm <script>` in the `product_merge_gate`
|
||||
job, on the same condition as `merge_gate`, without browsers and without the
|
||||
gate log and evidence artifacts of `ci:gate`. Make that job a required check
|
||||
of the branch where it has to block a merge. `check:ci` refuses a script that
|
||||
`package.json` does not define and counts these scripts as gated.
|
||||
|
||||
The slot as stored in `config/ci/gates.json` still follows the same contract
|
||||
rules. The contract allows the steps `checkout`, `setup-node`,
|
||||
`frozen-install`, `download` (the `promoted-release` transfer), `extract`, and
|
||||
one final `deploy` step whose `script` names a package script. Its variables
|
||||
may only be the `CANDIDATE_ARCHIVE_SHA256` digest of `immutable_build` and
|
||||
|
||||
@@ -17,6 +17,7 @@ import {
|
||||
renderCiWorkflow,
|
||||
workflowGateExecutionFailures,
|
||||
} from "./generate-ci-workflow.ts";
|
||||
import { loadProductCiOverlay } from "./contracts/product-ci-overlay.ts";
|
||||
import {
|
||||
ciContractReportSchema,
|
||||
} from "./lib/ci-contract-report.ts";
|
||||
@@ -40,6 +41,9 @@ import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
|
||||
const contract = await loadCiGateContract(process.cwd());
|
||||
const index = indexCiGateContract(contract);
|
||||
// 1103/12-07. The product's merge gates are entry scripts of CI as well.
|
||||
const { mergeGates: productGates } = await loadProductCiOverlay(process.cwd());
|
||||
const productGateScripts = productGates.map(({ script }) => script);
|
||||
const [packageDocument, nodeVersion] = await Promise.all([
|
||||
readFile("package.json", "utf8").then((value) => JSON.parse(value) as { scripts?: Record<string, string> }),
|
||||
readFile(".nvmrc", "utf8").then((value) => value.trim()),
|
||||
@@ -85,7 +89,7 @@ try {
|
||||
testFiles: await listTestFiles(process.cwd()),
|
||||
gatedPaths: gatedTestPaths(
|
||||
packageScripts,
|
||||
contract.commands.map(({ script }) => script),
|
||||
[...contract.commands.map(({ script }) => script), ...productGateScripts],
|
||||
(file) => readFileSync(file, "utf8"),
|
||||
),
|
||||
exclusions: parseUngatedTestExclusions(
|
||||
@@ -100,7 +104,7 @@ try {
|
||||
// 12-04: every verification package script is reached by a gate, or
|
||||
// config/ci/ungated-scripts.json says why not.
|
||||
try {
|
||||
const entryScripts = contract.commands.map(({ script }) => script);
|
||||
const entryScripts = [...contract.commands.map(({ script }) => script), ...productGateScripts];
|
||||
failures.push(
|
||||
...ungatedScriptFailures({
|
||||
scripts: packageScripts,
|
||||
@@ -148,10 +152,11 @@ for (const readiness of Object.keys(PROMOTION_FORMULA) as Array<keyof typeof PRO
|
||||
}
|
||||
if (!Object.values(allPass).every(Boolean)) failures.push("all-PASS formula did not produce every readiness state");
|
||||
|
||||
const renderedWorkflow = renderCiWorkflow(contract);
|
||||
const renderedWorkflow = renderCiWorkflow(contract, productGates);
|
||||
const workflowCheck = await generateCiWorkflow({
|
||||
root: process.cwd(),
|
||||
contract,
|
||||
productGates,
|
||||
check: true,
|
||||
});
|
||||
if (!workflowCheck.matches) {
|
||||
@@ -165,7 +170,9 @@ try {
|
||||
} catch (error) {
|
||||
failures.push(`generated workflow is unreadable: ${error instanceof Error ? error.message : String(error)}`);
|
||||
}
|
||||
failures.push(...workflowGateExecutionFailures(contract, checkedWorkflowBytes.toString("utf8")));
|
||||
failures.push(
|
||||
...workflowGateExecutionFailures(contract, checkedWorkflowBytes.toString("utf8"), productGates),
|
||||
);
|
||||
const report = ciContractReportSchema.parse({
|
||||
schemaVersion: 2,
|
||||
nodeVersion,
|
||||
|
||||
@@ -14,6 +14,7 @@ import {
|
||||
validateNpmScopeEnvironment,
|
||||
validatePackageScriptGraph,
|
||||
} from "../lib/package-script-graph.ts";
|
||||
import { loadProductCiOverlay, withProductDeployment } from "./product-ci-overlay.ts";
|
||||
import { PROMOTED_UPLOAD_PATHS } from "./promotion-artifacts.ts";
|
||||
|
||||
const ciActionRegistrationSchema = z
|
||||
@@ -583,20 +584,30 @@ export function parseCiGateContract(value: unknown): CiGateContract {
|
||||
export async function loadCiGateContract(
|
||||
root = process.cwd(),
|
||||
): Promise<CiGateContract> {
|
||||
const [rawContract, rawPackage] = await Promise.all([
|
||||
const [rawContract, rawPackage, overlay] = await Promise.all([
|
||||
readFile(path.join(root, "config/ci/gates.json"), "utf8"),
|
||||
readFile(path.join(root, "package.json"), "utf8"),
|
||||
loadProductCiOverlay(root),
|
||||
]);
|
||||
const contract = parseCiGateContract(JSON.parse(rawContract));
|
||||
const template = parseCiGateContract(JSON.parse(rawContract));
|
||||
// 1103/12-07. The product fills the deployment slot in its own overlay; the
|
||||
// filled contract is parsed again, so the template's slot rules hold.
|
||||
const contract = overlay.deployment === null
|
||||
? template
|
||||
: parseCiGateContract(withProductDeployment(JSON.parse(rawContract), overlay.deployment));
|
||||
const packageDocument = z
|
||||
.object({ scripts: z.record(z.string(), z.string()).default({}) })
|
||||
.passthrough()
|
||||
.parse(JSON.parse(rawPackage));
|
||||
// 1101/13-01. A filled deployment slot runs a package script in CI, under the
|
||||
// same existence and script-graph rules as a gate command.
|
||||
const deployScripts = contract.jobs.flatMap(({ steps }) =>
|
||||
steps.flatMap((step) => (step.kind === "deploy" && step.script ? [step.script] : [])),
|
||||
);
|
||||
// same existence and script-graph rules as a gate command. So does a
|
||||
// product merge gate (1103/12-07).
|
||||
const deployScripts = [
|
||||
...contract.jobs.flatMap(({ steps }) =>
|
||||
steps.flatMap((step) => (step.kind === "deploy" && step.script ? [step.script] : [])),
|
||||
),
|
||||
...overlay.mergeGates.map(({ script }) => script),
|
||||
];
|
||||
const missing = [...contract.commands.map((command) => command.script), ...deployScripts]
|
||||
.filter((script, index, scripts) => scripts.indexOf(script) === index)
|
||||
.filter((script) => !packageDocument.scripts[script]);
|
||||
@@ -643,7 +654,8 @@ export async function loadCiGateContract(
|
||||
`CI package script install policy invalid:\n${installPolicyFailures.join("\n")}`,
|
||||
);
|
||||
}
|
||||
await assertCiContractBaseline(root, contract);
|
||||
// The baseline describes the template contract; the overlay is the product's.
|
||||
await assertCiContractBaseline(root, template);
|
||||
return contract;
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,146 @@
|
||||
import { readFile } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
import { z } from "zod";
|
||||
|
||||
/**
|
||||
* 1103/12-07. The product's own part of CI, kept out of the template-owned
|
||||
* config/ci/gates.json so a template sync never meets it. The template ships
|
||||
* this file empty and does not change it. It may hold only:
|
||||
*
|
||||
* - `deployment`: the package script that deploys the promoted release, and
|
||||
* its `vars.*` / `secrets.*` bindings. The template renders the rest of the
|
||||
* slot (download the promoted-release transfer, extract it against the
|
||||
* candidate digest, then run the script); secrets reach the deploy step only
|
||||
* (1103/13-05).
|
||||
* - `mergeGates`: product checks that run on every merge-stage run, in a job
|
||||
* of their own (`product_merge_gate`). Their ids are `PRODUCT-GATE-NNN`, so
|
||||
* they never take or change a template gate (`FE-GATE-NNN`), its commands,
|
||||
* artifacts or readiness formula. The template contract baseline counts
|
||||
* only the template contract.
|
||||
*/
|
||||
export const PRODUCT_CI_OVERLAY_PATH = "config/ci/product-gates.json";
|
||||
|
||||
const scriptName = z
|
||||
.string()
|
||||
.max(128)
|
||||
.regex(/^[A-Za-z0-9:_-]+$/u, "a product script is a package script name ([A-Za-z0-9:_-])");
|
||||
const binding = z
|
||||
.object({
|
||||
name: z.string().regex(/^[A-Z][A-Z0-9_]*$/u),
|
||||
value: z
|
||||
.string()
|
||||
.regex(
|
||||
/^\$\{\{ (?:vars|secrets)\.[A-Za-z_][A-Za-z0-9_]* \}\}$/u,
|
||||
"a product binding must be a vars.* or secrets.* value",
|
||||
),
|
||||
})
|
||||
.strict();
|
||||
const productGate = z
|
||||
.object({
|
||||
id: z
|
||||
.string()
|
||||
.regex(/^PRODUCT-GATE-\d{3}$/u, "product gate ids are PRODUCT-GATE-NNN; FE-GATE-NNN ids belong to the template"),
|
||||
name: z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/u),
|
||||
script: scriptName,
|
||||
})
|
||||
.strict();
|
||||
|
||||
const productCiOverlaySchema = z
|
||||
.object({
|
||||
schemaVersion: z.literal(1),
|
||||
deployment: z
|
||||
.object({ script: scriptName, environment: z.array(binding).max(32) })
|
||||
.strict()
|
||||
.nullable(),
|
||||
mergeGates: z.array(productGate).max(32),
|
||||
})
|
||||
.strict()
|
||||
.superRefine((overlay, context) => {
|
||||
const issue = (message: string) => context.addIssue({ code: "custom", message });
|
||||
const names = overlay.deployment?.environment.map(({ name }) => name) ?? [];
|
||||
if (new Set(names).size !== names.length) issue("duplicate deployment binding name");
|
||||
if (names.includes("CANDIDATE_ARCHIVE_SHA256")) {
|
||||
issue("CANDIDATE_ARCHIVE_SHA256 is bound by the template to the immutable_build digest");
|
||||
}
|
||||
for (const field of ["id", "name"] as const) {
|
||||
const values = overlay.mergeGates.map((gate) => gate[field]);
|
||||
if (new Set(values).size !== values.length) issue(`duplicate product gate ${field}`);
|
||||
}
|
||||
});
|
||||
|
||||
export type ProductCiOverlay = z.infer<typeof productCiOverlaySchema>;
|
||||
export type ProductDeployment = NonNullable<ProductCiOverlay["deployment"]>;
|
||||
export type ProductGate = ProductCiOverlay["mergeGates"][number];
|
||||
|
||||
const EMPTY_PRODUCT_CI_OVERLAY: ProductCiOverlay = Object.freeze({
|
||||
schemaVersion: 1,
|
||||
deployment: null,
|
||||
mergeGates: [],
|
||||
});
|
||||
|
||||
export function parseProductCiOverlay(value: unknown): ProductCiOverlay {
|
||||
const result = productCiOverlaySchema.safeParse(value);
|
||||
if (!result.success) {
|
||||
throw new TypeError(
|
||||
`${PRODUCT_CI_OVERLAY_PATH} invalid:\n${result.error.issues
|
||||
.map((issue) => `${issue.path.join(".") || "root"}: ${issue.message}`)
|
||||
.join("\n")}`,
|
||||
);
|
||||
}
|
||||
return result.data;
|
||||
}
|
||||
|
||||
/** The overlay of `root`; a checkout without the file (synced before it existed) has none. */
|
||||
export async function loadProductCiOverlay(root: string): Promise<ProductCiOverlay> {
|
||||
let text: string;
|
||||
try {
|
||||
text = await readFile(path.join(root, PRODUCT_CI_OVERLAY_PATH), "utf8");
|
||||
} catch (error) {
|
||||
if ((error as NodeJS.ErrnoException).code === "ENOENT") return EMPTY_PRODUCT_CI_OVERLAY;
|
||||
throw error;
|
||||
}
|
||||
return parseProductCiOverlay(JSON.parse(text));
|
||||
}
|
||||
|
||||
const PROMOTED_DOWNLOAD_PATH = ".release/deployment";
|
||||
/** Where the slot extracts the promoted archive; the deploy script uploads `<this>/dist`. */
|
||||
export const PROMOTED_RELEASE_ROOT = ".release/promoted-release";
|
||||
|
||||
/**
|
||||
* The template contract document with its empty deployment slot filled from
|
||||
* the overlay. The caller parses the result, so the slot rules of the
|
||||
* template contract still apply. A slot the template contract already
|
||||
* filled is refused: the slot has one owner.
|
||||
*/
|
||||
export function withProductDeployment(contract: unknown, deployment: ProductDeployment): unknown {
|
||||
const document = structuredClone(contract) as { jobs?: { id?: unknown; steps?: unknown; environment?: unknown }[] };
|
||||
const slot = document.jobs?.find(({ id }) => id === "deployment");
|
||||
if (
|
||||
!slot ||
|
||||
JSON.stringify(slot.steps) !== JSON.stringify([{ kind: "deploy" }]) ||
|
||||
JSON.stringify(slot.environment) !== "[]"
|
||||
) {
|
||||
throw new TypeError(
|
||||
`the deployment slot is filled in config/ci/gates.json and in ${PRODUCT_CI_OVERLAY_PATH}; ` +
|
||||
`keep the template slot empty and fill ${PRODUCT_CI_OVERLAY_PATH}`,
|
||||
);
|
||||
}
|
||||
slot.environment = [
|
||||
{ name: "CANDIDATE_ARCHIVE_SHA256", value: "${{ needs.immutable_build.outputs.archive_sha256 }}" },
|
||||
...deployment.environment,
|
||||
];
|
||||
slot.steps = [
|
||||
{ kind: "checkout" },
|
||||
{ kind: "setup-node" },
|
||||
{ kind: "frozen-install" },
|
||||
{ kind: "download", transferId: "promoted-release", path: PROMOTED_DOWNLOAD_PATH },
|
||||
{
|
||||
kind: "extract",
|
||||
archivePath: `${PROMOTED_DOWNLOAD_PATH}/release-candidate.tar.gz`,
|
||||
targetRoot: PROMOTED_RELEASE_ROOT,
|
||||
},
|
||||
{ kind: "deploy", script: deployment.script },
|
||||
];
|
||||
return document;
|
||||
}
|
||||
@@ -18,6 +18,7 @@ import {
|
||||
type CiWorkflowJob,
|
||||
type CiWorkflowStep,
|
||||
} from "./contracts/ci-gates.ts";
|
||||
import { loadProductCiOverlay, type ProductGate } from "./contracts/product-ci-overlay.ts";
|
||||
import {
|
||||
assertSafeExistingPublishPath,
|
||||
assertSafePublishLeaf,
|
||||
@@ -27,6 +28,8 @@ import {
|
||||
export type GenerateCiWorkflowOptions = Readonly<{
|
||||
root: string;
|
||||
contract?: CiGateContract;
|
||||
/** Product merge gates; read from the root's config/ci/product-gates.json when omitted. */
|
||||
productGates?: readonly ProductGate[];
|
||||
check: boolean;
|
||||
}>;
|
||||
|
||||
@@ -61,7 +64,10 @@ const defaultFileSystem: CiWorkflowFileSystem = Object.freeze({
|
||||
rm: async (target) => rm(target, { force: true }),
|
||||
});
|
||||
|
||||
export function renderCiWorkflow(contract: CiGateContract): string {
|
||||
export function renderCiWorkflow(
|
||||
contract: CiGateContract,
|
||||
productGates: readonly ProductGate[] = [],
|
||||
): string {
|
||||
const index = indexCiGateContract(contract);
|
||||
const transfers = new Map<string, { name: string }>();
|
||||
for (const job of contract.jobs) {
|
||||
@@ -108,9 +114,48 @@ export function renderCiWorkflow(contract: CiGateContract): string {
|
||||
if (jobIndex > 0) lines.push("");
|
||||
lines.push(...renderJob(job, index, transfers));
|
||||
}
|
||||
if (productGates.length > 0) lines.push("", ...renderProductGateJob(productGates));
|
||||
return `${lines.join("\n").replace(/\n+$/u, "")}\n`;
|
||||
}
|
||||
|
||||
/**
|
||||
* 1103/12-07. The product's merge gates (config/ci/product-gates.json) run in
|
||||
* a job after every template job, on the same merge condition. A product gate
|
||||
* is one package script; it has no log artifact or evidence of the template
|
||||
* gate contract and is not part of its readiness formula, so the product makes
|
||||
* this job a required check where it wants it to block a merge.
|
||||
*/
|
||||
function renderProductGateJob(productGates: readonly ProductGate[]): string[] {
|
||||
return [
|
||||
" product_merge_gate:",
|
||||
` name: ${yamlScalar("${{ matrix.gate }} / ${{ matrix.name }}")}`,
|
||||
` if: ${renderCondition("merge")}`,
|
||||
" runs-on: ubuntu-latest",
|
||||
" timeout-minutes: 45",
|
||||
" strategy:",
|
||||
" fail-fast: false",
|
||||
" matrix:",
|
||||
" include:",
|
||||
...productGates.map(
|
||||
(gate) => ` - { gate: ${gate.id}, name: ${gate.name}, script: ${yamlScalar(gate.script)} }`,
|
||||
),
|
||||
" steps:",
|
||||
` - uses: ${requiredStepActionUses("checkout")}`,
|
||||
" with:",
|
||||
" persist-credentials: false",
|
||||
` - uses: ${requiredStepActionUses("setup-node")}`,
|
||||
" with:",
|
||||
" node-version-file: .nvmrc",
|
||||
" - name: Frozen install",
|
||||
" run: |",
|
||||
" corepack enable",
|
||||
" corepack pnpm install --frozen-lockfile --ignore-scripts",
|
||||
// The overlay limits the script to [A-Za-z0-9:_-], a plain shell word.
|
||||
" - name: Run product gate",
|
||||
" run: corepack pnpm ${{ matrix.script }}",
|
||||
];
|
||||
}
|
||||
|
||||
function renderJob(
|
||||
job: CiWorkflowJob,
|
||||
index: ReturnType<typeof indexCiGateContract>,
|
||||
@@ -403,9 +448,22 @@ function runGateStepName(jobId: string, gateId: string): string {
|
||||
export function workflowGateExecutionFailures(
|
||||
contract: CiGateContract,
|
||||
workflow: string,
|
||||
productGates: readonly ProductGate[] = [],
|
||||
): string[] {
|
||||
const executed = new Set<string>();
|
||||
for (const job of workflow.split(/^(?= {2}[a-z_]+:$)/mu)) {
|
||||
const jobs = workflow.split(/^(?= {2}[a-z_]+:$)/mu);
|
||||
const productJob = jobs.find((job) => job.startsWith(" product_merge_gate:\n")) ?? "";
|
||||
const productRuns = /^ {8}run: corepack pnpm \$\{\{ matrix\.script \}\}$/mu.test(productJob);
|
||||
const productFailures = productGates
|
||||
.filter(
|
||||
(gate) =>
|
||||
!productRuns ||
|
||||
!productJob.includes(
|
||||
` - { gate: ${gate.id}, name: ${gate.name}, script: ${yamlScalar(gate.script)} }\n`,
|
||||
),
|
||||
)
|
||||
.map(({ id }) => `product gate is not executed by the product_merge_gate job: ${id}`);
|
||||
for (const job of jobs) {
|
||||
for (const match of job.matchAll(/^ +run: corepack pnpm ci:gate -- (FE-GATE-\d{3})$/gmu)) {
|
||||
executed.add(match[1]!);
|
||||
}
|
||||
@@ -415,9 +473,12 @@ export function workflowGateExecutionFailures(
|
||||
}
|
||||
}
|
||||
}
|
||||
return contract.gates
|
||||
.filter(({ id }) => !executed.has(id))
|
||||
.map(({ id }) => `gate is not executed by any workflow run step: ${id}`);
|
||||
return [
|
||||
...contract.gates
|
||||
.filter(({ id }) => !executed.has(id))
|
||||
.map(({ id }) => `gate is not executed by any workflow run step: ${id}`),
|
||||
...productFailures,
|
||||
];
|
||||
}
|
||||
|
||||
function humanize(value: string): string {
|
||||
@@ -439,7 +500,8 @@ export function createCiWorkflowGenerator(
|
||||
if (path.relative(root, target).startsWith("..") || path.relative(root, target) === "") {
|
||||
throw new TypeError(`workflow target escapes repository root: ${contract.providerAdapter}`);
|
||||
}
|
||||
const expected = Buffer.from(renderCiWorkflow(contract), "utf8");
|
||||
const productGates = options.productGates ?? (await loadProductCiOverlay(root)).mergeGates;
|
||||
const expected = Buffer.from(renderCiWorkflow(contract, productGates), "utf8");
|
||||
let actual: Buffer | null = null;
|
||||
const existingPathIsSafe =
|
||||
fileSystem === defaultFileSystem
|
||||
|
||||
@@ -226,7 +226,7 @@ if (status === "FAIL") {
|
||||
}
|
||||
if (status === "UNVERIFIED" && slotEmpty) {
|
||||
process.stderr.write(
|
||||
"Hosting header contract: UNVERIFIED (the deployment slot is empty: nothing deployed this release, so the host was not probed; fill the deployment job in config/ci/gates.json)\n",
|
||||
"Hosting header contract: UNVERIFIED (the deployment slot is empty: nothing deployed this release, so the host was not probed; fill deployment in config/ci/product-gates.json)\n",
|
||||
);
|
||||
process.exit(3);
|
||||
}
|
||||
|
||||
@@ -0,0 +1,184 @@
|
||||
import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
|
||||
import { afterEach, describe, expect, it } from "vitest";
|
||||
|
||||
import { loadCiGateContract } from "../../scripts/contracts/ci-gates.ts";
|
||||
import {
|
||||
loadProductCiOverlay,
|
||||
parseProductCiOverlay,
|
||||
PRODUCT_CI_OVERLAY_PATH,
|
||||
} from "../../scripts/contracts/product-ci-overlay.ts";
|
||||
import { renderCiWorkflow, workflowGateExecutionFailures } from "../../scripts/generate-ci-workflow.ts";
|
||||
|
||||
/**
|
||||
* 1103/12-07. A product attached its deployment and its own merge checks by
|
||||
* editing the template-owned config/ci/gates.json (3,000 lines) and the
|
||||
* generated workflow, and met them again in every template sync. The product
|
||||
* now writes them in config/ci/product-gates.json, which the template ships
|
||||
* empty and never changes.
|
||||
*/
|
||||
const roots: string[] = [];
|
||||
|
||||
afterEach(async () => {
|
||||
await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
|
||||
});
|
||||
|
||||
async function productRoot(
|
||||
overlay: unknown,
|
||||
extraScripts: Readonly<Record<string, string>> = {},
|
||||
): Promise<string> {
|
||||
const root = await mkdtemp(path.join(tmpdir(), "product-ci-overlay-"));
|
||||
roots.push(root);
|
||||
await mkdir(path.join(root, "config/ci"), { recursive: true });
|
||||
for (const file of ["config/ci/gates.json", "config/ci/contract-baseline.json"]) {
|
||||
await writeFile(path.join(root, file), await readFile(file));
|
||||
}
|
||||
const packageDocument = JSON.parse(await readFile("package.json", "utf8")) as {
|
||||
scripts: Record<string, string>;
|
||||
};
|
||||
Object.assign(packageDocument.scripts, extraScripts);
|
||||
await writeFile(path.join(root, "package.json"), JSON.stringify(packageDocument, null, 2));
|
||||
await writeFile(path.join(root, PRODUCT_CI_OVERLAY_PATH), JSON.stringify(overlay, null, 2));
|
||||
return root;
|
||||
}
|
||||
|
||||
const DEPLOYMENT = {
|
||||
script: "deploy:desktop",
|
||||
environment: [
|
||||
{ name: "DEPLOY_HOST", value: "${{ vars.DEPLOY_HOST }}" },
|
||||
{ name: "DEPLOY_SSH_KEY", value: "${{ secrets.DEPLOY_SSH_KEY }}" },
|
||||
],
|
||||
};
|
||||
const DEPLOY_SCRIPTS = { "deploy:desktop": "node scripts/deploy-desktop.ts" };
|
||||
const GATE = { id: "PRODUCT-GATE-001", name: "backend-contract", script: "check:backend-contract" };
|
||||
const GATE_SCRIPTS = { "check:backend-contract": "node scripts/check-backend-contract.ts" };
|
||||
|
||||
describe("product CI overlay (1103/12-07)", () => {
|
||||
it("ships empty, so the template's own workflow is unchanged", async () => {
|
||||
expect(await loadProductCiOverlay(process.cwd())).toEqual({
|
||||
schemaVersion: 1,
|
||||
deployment: null,
|
||||
mergeGates: [],
|
||||
});
|
||||
});
|
||||
|
||||
it("fills the deployment slot with the promoted candidate and the product's script", async () => {
|
||||
const root = await productRoot(
|
||||
{ schemaVersion: 1, deployment: DEPLOYMENT, mergeGates: [] },
|
||||
DEPLOY_SCRIPTS,
|
||||
);
|
||||
|
||||
// The template baseline (config/ci/contract-baseline.json) is unchanged.
|
||||
const contract = await loadCiGateContract(root);
|
||||
const slot = contract.jobs.find(({ id }) => id === "deployment");
|
||||
expect(slot?.steps.map(({ kind }) => kind)).toEqual([
|
||||
"checkout",
|
||||
"setup-node",
|
||||
"frozen-install",
|
||||
"download",
|
||||
"extract",
|
||||
"deploy",
|
||||
]);
|
||||
expect(slot?.steps).toContainEqual(expect.objectContaining({ kind: "download", transferId: "promoted-release" }));
|
||||
expect(slot?.steps.at(-1)).toEqual({ kind: "deploy", script: "deploy:desktop" });
|
||||
expect(slot?.environment).toEqual([
|
||||
{ name: "CANDIDATE_ARCHIVE_SHA256", value: "${{ needs.immutable_build.outputs.archive_sha256 }}" },
|
||||
...DEPLOYMENT.environment,
|
||||
]);
|
||||
|
||||
const workflow = renderCiWorkflow(contract);
|
||||
const job = workflow.slice(workflow.indexOf(" deployment:\n"), workflow.indexOf(" production_gate:\n"));
|
||||
expect(job).toContain("corepack pnpm deploy:desktop");
|
||||
expect(job.match(/secrets\./gu)).toHaveLength(1);
|
||||
});
|
||||
|
||||
it("refuses a slot filled in the template contract and in the overlay", async () => {
|
||||
const root = await productRoot(
|
||||
{ schemaVersion: 1, deployment: DEPLOYMENT, mergeGates: [] },
|
||||
DEPLOY_SCRIPTS,
|
||||
);
|
||||
const gatesPath = path.join(root, "config/ci/gates.json");
|
||||
const gates = JSON.parse(await readFile(gatesPath, "utf8")) as {
|
||||
jobs: { id: string; steps: unknown[]; environment: unknown[] }[];
|
||||
};
|
||||
const slot = gates.jobs.find(({ id }) => id === "deployment")!;
|
||||
slot.environment = [
|
||||
{ name: "CANDIDATE_ARCHIVE_SHA256", value: "${{ needs.immutable_build.outputs.archive_sha256 }}" },
|
||||
];
|
||||
slot.steps = [
|
||||
{ kind: "download", transferId: "promoted-release", path: ".release/promoted" },
|
||||
{
|
||||
kind: "extract",
|
||||
archivePath: ".release/promoted/release-candidate.tar.gz",
|
||||
targetRoot: ".release/promoted-release",
|
||||
},
|
||||
{ kind: "deploy", script: "deploy:desktop" },
|
||||
];
|
||||
await writeFile(gatesPath, JSON.stringify(gates));
|
||||
|
||||
await expect(loadCiGateContract(root)).rejects.toThrow(/product-gates\.json/u);
|
||||
});
|
||||
|
||||
it("refuses an overlay script that package.json does not define", async () => {
|
||||
const root = await productRoot({ schemaVersion: 1, deployment: DEPLOYMENT, mergeGates: [GATE] });
|
||||
|
||||
await expect(loadCiGateContract(root)).rejects.toThrow(
|
||||
/missing package scripts: deploy:desktop, check:backend-contract/u,
|
||||
);
|
||||
});
|
||||
|
||||
it("runs product merge gates in a job of their own, apart from the template gates", async () => {
|
||||
const root = await productRoot(
|
||||
{ schemaVersion: 1, deployment: null, mergeGates: [GATE] },
|
||||
GATE_SCRIPTS,
|
||||
);
|
||||
const contract = await loadCiGateContract(root);
|
||||
const { mergeGates } = await loadProductCiOverlay(root);
|
||||
|
||||
const workflow = renderCiWorkflow(contract, mergeGates);
|
||||
const job = workflow.slice(workflow.indexOf(" product_merge_gate:\n"));
|
||||
expect(job).toContain(' - { gate: PRODUCT-GATE-001, name: backend-contract, script: "check:backend-contract" }');
|
||||
expect(job).toContain(" run: corepack pnpm ${{ matrix.script }}");
|
||||
expect(job).toContain(` if: ${"${{ gitea.event_name != 'workflow_dispatch' || inputs.stage != 'documentation' }}"}`);
|
||||
expect(workflowGateExecutionFailures(contract, workflow, mergeGates)).toEqual([]);
|
||||
// The template part of the workflow is the same bytes with or without the overlay.
|
||||
expect(workflow.startsWith(renderCiWorkflow(contract).trimEnd())).toBe(true);
|
||||
|
||||
expect(workflowGateExecutionFailures(contract, renderCiWorkflow(contract), mergeGates)).toEqual([
|
||||
"product gate is not executed by the product_merge_gate job: PRODUCT-GATE-001",
|
||||
]);
|
||||
});
|
||||
|
||||
it.each([
|
||||
["a template gate id", { mergeGates: [{ ...GATE, id: "FE-GATE-030" }] }, /PRODUCT-GATE-NNN/u],
|
||||
["a duplicate gate id", { mergeGates: [GATE, { ...GATE, name: "other" }] }, /duplicate product gate/u],
|
||||
[
|
||||
"a binding to another job's output",
|
||||
{
|
||||
deployment: {
|
||||
...DEPLOYMENT,
|
||||
environment: [{ name: "NONCE", value: "${{ needs.promotion.outputs.staging_root }}" }],
|
||||
},
|
||||
},
|
||||
/vars\.\* or secrets\.\*/u,
|
||||
],
|
||||
[
|
||||
"the candidate digest the template binds",
|
||||
{
|
||||
deployment: {
|
||||
...DEPLOYMENT,
|
||||
environment: [{ name: "CANDIDATE_ARCHIVE_SHA256", value: "${{ vars.DIGEST }}" }],
|
||||
},
|
||||
},
|
||||
/CANDIDATE_ARCHIVE_SHA256/u,
|
||||
],
|
||||
["a script that is not a plain name", { deployment: { ...DEPLOYMENT, script: "deploy; rm -rf ." } }, /script/u],
|
||||
["an unknown field", { gates: [] }, /unrecognized|Unrecognized/u],
|
||||
] as const)("refuses %s", (_name, change, diagnostic) => {
|
||||
expect(() =>
|
||||
parseProductCiOverlay({ schemaVersion: 1, deployment: null, mergeGates: [], ...change }),
|
||||
).toThrow(diagnostic);
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user