문제 .env.example과 운영 문서는 runtime config를 재빌드 없이 바꿀 수 있다고 적는다(SERVICE_WORKER DISABLED, FEATURE_OVERRIDES). 그런데 고친 문서를 검사할 명령이 없다. check:release-admission은 dist/config.json만 읽고, build:profile은 BUILD_ID를 덮어 다시 만든다. 브라우저는 부팅 때 문서를 스키마로 검사하고 BUILD_ID를 HTML과 맞춰 보므로, 오타 하나나 BUILD_ID 변경 하나가 모든 사용자의 BOOT_CONFIG_FAILURE가 된다. FE-RB-001은 세 줄이고 고치는 방법이 없다. 고른 방법 - check-release-admission.ts가 `--config <고친 사본> --original <배포된 원본>`을 받는다. 사본에 기존 검사(스키마, 대상 규칙)를 그대로 돌리고, 원본과 비교해 CAPABILITY_OVERRIDES·FEATURE_OVERRIDES 밖의 필드가 하나라도 바뀌면 거절한다. BUILD_ID·RELEASE_ID 유지는 이 규칙에 들어 있다. `--original` 없이 `--config`만 주면 거절한다(비교 대상 없이 통과시키지 않는다). - 사본 검사는 artifacts/release/deployment-admission.json을 쓰지 않는다. 그 파일은 빌드의 승인 증거(CI artifact)이고 운영자의 사본은 빌드가 아니다. - FE-RB-001에 네 단계(사본 두 개 받기·고치기 → 검사 → 같은 파일시스템에서 rename으로 교체, 되돌리기도 같은 방법 → 깨끗한 세션 부팅 확인)를 적고, release-cache-rollback.md와 browser-file-storage-recovery.md의 스위치 설명이 그 절차를 가리킨다. .env.example 문장을 "비상 스위치만 재빌드 없이 바꾼다"로 좁혔다. - pnpm이 `--`를 넘겨도 되도록 맨 앞 `--`를 버린다. 버린 대안 - `--build-id <id>`로 BUILD_ID만 대조: API_BASE_URL·RELEASE_MANIFEST_URL처럼 빌드가 정한 다른 필드를 바꿔도 통과한다. 원본 전체 비교가 같은 비용으로 더 좁다. - release-manifest.json에서 build id를 읽기: 운영자가 받을 파일이 하나 더 늘고, 여전히 BUILD_ID만 본다. - 비상 스위치도 빌드로만 바꾸기: 장애 대응 시간이 빌드·승격 시간만큼 늘어 스위치의 목적이 사라진다(리뷰 대안 비교). 위험·한계 - 원본과 사본의 중첩 객체 비교는 JSON.stringify라 키 순서만 달라도 "바뀜"으로 거절한다(닫힌 쪽으로 실패). - 실제 서버에서 사본을 바꿔 부팅해 보지 않았다. 바뀐 문서가 release 기록(checksums.txt, 승격 archive)과 달라지는 점은 런북에 적기만 했다. 검증 - RED: node scripts/run-vitest.ts run tests/unit/deployment-admission.test.ts 새 6건 실패. 모두 "release admission refused: dist/config.json is unreadable"(--config를 무시하고 dist를 읽음) - GREEN: 같은 파일 22 passed. 스위치만 바꾼 사본 ADMITTED·기록 없음, SERVICE_WORKER "DISABLE" 오타·BUILD_ID/RELEASE_ID/API_BASE_URL 변경· --original 누락은 exit 1 - runbook-contract, runbook-drill, feature-override-diagnostics 포함 35 passed - 실제 local 빌드에서 인자 없는 기존 경로 ADMITTED(기록 작성), `-- --config dist/config.json --original public/config.json` ADMITTED - tsc(node, test), eslint 바뀐 파일, verify-documentation-readiness PASS_SCOPED Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-05
33 lines
1.8 KiB
Markdown
33 lines
1.8 KiB
Markdown
# FE-RB-001 — Boot configuration failure
|
|
|
|
Trigger on `BOOT_CONFIG_FAILURE` after the single bounded refetch fails. Stop
|
|
product route mounting and show the safe support shell; the planned owner
|
|
triage target is five minutes. Escalate from the environment/config owner to
|
|
the release owner.
|
|
|
|
Close only after a clean-session boot mounts the product root, config
|
|
validation evidence passes, and repeated boot-error telemetry is absent.
|
|
|
|
## Changing an emergency switch without a rebuild
|
|
|
|
Only `CAPABILITY_OVERRIDES` and `FEATURE_OVERRIDES` may change in a deployed
|
|
`config.json`. Every browser validates the document on boot, so a typo there
|
|
causes this runbook's failure for every user. Change it in four steps:
|
|
|
|
1. Download the deployed `config.json` twice, as `deployed.json` (keep it as
|
|
is) and `edited.json`. Change only the switch in `edited.json`.
|
|
2. From a checkout of the deployed commit, run
|
|
`RELEASE_TARGET=<environment> corepack pnpm check:release-admission --config /abs/edited.json --original /abs/deployed.json`
|
|
(absolute paths: pnpm runs it from the repository root). It must print
|
|
`ADMITTED`. It refuses a schema error, a target rule, and any changed field
|
|
other than the two switches, `BUILD_ID` and `RELEASE_ID` included.
|
|
3. Upload `edited.json` next to the live file and rename it over
|
|
`config.json` on the same filesystem. Never edit the live file in place.
|
|
To undo, rename `deployed.json` back the same way.
|
|
4. Boot in a clean session (new browser profile) and see the product root
|
|
mount. The switch takes effect on the next boot only.
|
|
|
|
The served document then differs from the release record (`checksums.txt`,
|
|
the promoted archive). Note the change in the release log, and put it in the
|
|
profile (`config/runtime/<environment>.json`) for the next build.
|