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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user