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:
DongHyeonka
2026-11-04 20:48:50 +09:00
parent 2e12d2f0d1
commit 4c4248aac5
9 changed files with 473 additions and 21 deletions
+1
View File
@@ -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절).
정본 표에 없는 것:
+38 -3
View File
@@ -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