From 4c4248aac54bec50a84fdbbfb4905cdaaf4a0a4c Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 20:48:50 +0900 Subject: [PATCH] =?UTF-8?q?feat(ci):=20=EC=A0=9C=ED=92=88=EC=9D=B4=20?= =?UTF-8?q?=EB=B0=B0=ED=8F=AC=20job=EA=B3=BC=20merge=20=EA=B2=80=EC=82=AC?= =?UTF-8?q?=EB=A5=BC=20=EC=A0=9C=ED=92=88=20=EC=86=8C=EC=9C=A0=20overlay?= =?UTF-8?q?=EC=97=90=20=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 배포 슬롯을 채우거나 제품 전용 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 --- config/ci/product-gates.json | 5 + docs/manual/03-outside-feature-folder.md | 1 + docs/operations/ci-quality-gates.md | 41 ++++- scripts/check-ci-contract.ts | 15 +- scripts/contracts/ci-gates.ts | 26 +++- scripts/contracts/product-ci-overlay.ts | 146 ++++++++++++++++++ scripts/generate-ci-workflow.ts | 74 ++++++++- scripts/verify-hosting-headers.ts | 2 +- tests/unit/product-ci-overlay.test.ts | 184 +++++++++++++++++++++++ 9 files changed, 473 insertions(+), 21 deletions(-) create mode 100644 config/ci/product-gates.json create mode 100644 scripts/contracts/product-ci-overlay.ts create mode 100644 tests/unit/product-ci-overlay.test.ts diff --git a/config/ci/product-gates.json b/config/ci/product-gates.json new file mode 100644 index 00000000..2849a590 --- /dev/null +++ b/config/ci/product-gates.json @@ -0,0 +1,5 @@ +{ + "schemaVersion": 1, + "deployment": null, + "mergeGates": [] +} diff --git a/docs/manual/03-outside-feature-folder.md b/docs/manual/03-outside-feature-folder.md index 1c13012f..0a777c43 100644 --- a/docs/manual/03-outside-feature-folder.md +++ b/docs/manual/03-outside-feature-folder.md @@ -107,6 +107,7 @@ release admission refused for staging: - `src/contracts/product-contracts.ts`: 제품 인증 프로필이나 제품 런타임 설정 키가 필요할 때. - 템플릿 파일 `src/contracts/rest-profiles.ts`는 고치지 않는다. - `config/runtime/.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절). 정본 표에 없는 것: diff --git a/docs/operations/ci-quality-gates.md b/docs/operations/ci-quality-gates.md index c54fd10e..63634d0f 100644 --- a/docs/operations/ci-quality-gates.md +++ b/docs/operations/ci-quality-gates.md @@ -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