Files
clean-architecture-frontend…/docs/operations/ci-quality-gates.md
DongHyeonka f21ea48911
frontend-quality-gates / merge / static checks (pull_request) Successful in 1m56s
frontend-quality-gates / merge / tests (pull_request) Successful in 15m58s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 6m15s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / self-tests and removal drills (pull_request) Skipped
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
ci(gates): 의존성 캐시를 checkout과 같은 파일시스템의 폴더에 둔다
문제: #41의 merge job 캐시는 hit해도 설치가 빨라지지 않았다. PR run
230에서 세 job 모두 복원했지만(222MB, 4.8초) pnpm 설치는 16.9·26.4·22.4초로
캐시 없는 run(13.8~22.8초)과 같았다. `reused 404, downloaded 0` 뒤 node_modules에
넣는 데만 15초 넘게 걸렸다. desktop 재현: 같은 파일시스템 2.1초, tar 왕복 뒤
7.6초, store가 다른 파일시스템이면 58.8초(하드링크 대신 복사). store가 job의
`/tmp`에 있어 checkout과 다른 파일시스템일 가능성이 크다.

고친 것(권하는 안으로 정함, 총괄): merge job의 첫 캐시 단계가
`scripts/ci/dependency-cache-root.sh "$RUNNER_TEMP" "$(dirname "$GITHUB_WORKSPACE")"`
를 돈다. 후보 중 checkout과 `stat -c %d`가 같고 checkout 밖인 첫 폴더를 고르고,
없으면 첫 후보를 쓴다. 고른 폴더, 견준 장치 번호, job 시작 때의 부하를 한
줄로 로그에 남기고, `COREPACK_HOME`·`PNPM_CONFIG_STORE_DIR`·
`PNPM_CONFIG_CACHE_DIR`를 `$GITHUB_ENV`로 넘긴다(job env 고정값을 뺌). 캐시
경로는 그 단계 출력을 쓴다. checkout 안은 후보가 아니다(`git status`, repo
배치 검사, 산출물에 잡히지 않게).

버린 대안: checkout 안 `.tmp` 아래(배치 검사·산출물에 걸림), workspace 부모를
고정 경로로(파일시스템이 같은지 runner마다 다를 수 있다).

위험·한계: 고른 폴더가 run마다 다르면 캐시 항목의 경로가 달라 hit하지 않는다
(같은 runner에서는 같다). 같은 파일시스템이 없으면 지금과 같다. runner에서의
효과는 main 저장 → 다음 PR 복원으로 잰다.

검증(desktop): 새 시험 `tests/unit/dependency-cache-root.test.ts`(가짜
`stat`으로 같은 파일시스템 고르기·checkout 안 제외·대체 경로) 통과, 최대
47ms. 생성 시험은 바꾸기 전 생성기에서 실패(RED), 고친 뒤
ci-workflow-generation·test-timeout-declarations·repository-layout 등 460개
통과. check:ci·check:types·eslint·verify:documentation rc=0.
2026-11-13 14:05:46 +09:00

630 lines
50 KiB
Markdown

# CI 품질 게이트 구성
`config/ci/gates.json`은 모든 게이트를 담은 실행 가능한 registry이고, workflow 모델은
이것 하나뿐이다. `.gitea/workflows/quality-gates.yml`은 이 엄격한 v2 계약에서 생성한다.
따로 설정을 정하는 정본이 아니다. registry를 고치고
`corepack pnpm generate:ci-workflow`를 돌린 뒤, 생성된 바이트를 함께 커밋한다.
`corepack pnpm check:ci-workflow`는 빠졌거나, 낡았거나, CRLF이거나, 그 밖에 바이트가 다른
출력을 거절한다. `corepack pnpm check:ci`는 산출물 schema 검사, 타입이 있는 계약 검사기,
이 workflow drift 검사를 돈다. merge 단계는 job 셋(`merge_static`, `merge_test`,
`merge_browser`)으로 돌고 job마다 설치를 한 번 한다. 게이트마다 ID 이름의 step이 하나씩
있고, 실패한 게이트가 다음 게이트를 건너뛰게 하지 않는다.
merge job 셋만 의존성 캐시를 쓴다(권하는 안으로 정함 2026-11-13, 총괄). setup-node 앞에서
Node toolcache, corepack이 받은 pnpm, pnpm store와 메타데이터 캐시를 `.nvmrc`와
`pnpm-lock.yaml` 해시 키로 복원한다. 저장은 main run만 한다. 캐시 항목은 다음 run이 믿는
입력이다. pnpm은 같은 lockfile의 공급망 검증 기록이 캐시에 있으면 검증을 다시 하지 않는다.
그래서 브랜치 run은 복원만 한다. frozen install은 캐시가 맞든 없든 늘 돈다. 항목이 없거나
깨지면 pnpm이 모자란 패키지만 내려받고 node_modules는 같다. FE-GATE-013의 시스템 컨테이너도
같은 store와 메타데이터 캐시를 받는다. 캐시 폴더는 checkout 밖, checkout과 같은 파일시스템에
둔다(`scripts/ci/dependency-cache-root.sh`). 다른 파일시스템이면 pnpm이 node_modules를 복사해,
캐시가 맞아도 설치가 빨라지지 않는다. 고른 폴더, 견준 장치 번호, job 시작 때의 부하를 job 로그에
한 줄 남긴다. release·promotion·provider job은 공급망 증거를
만들므로 매번 새로 설치한다. 이 규칙은 `scripts/contracts/ci-gates.ts`의 `DEPENDENCY_CACHE`와
계약 검사가 지킨다. runner의 캐시 저장소는 짝 백엔드와 함께 쓰고 크기 상한이 있다(platform-core
`infrastructure/ci/gitea-runner/config.yaml`). 검사기 자신의 음성 fixture와
gating 검사는 branch에 push한 뒤 main 단계(`main_gate`, FE-GATE-029)에서 돈다. 선택 runtime
제거 드릴 셋(FE-GATE-030)도 main 단계에서 돈다. PR runner 시간 약 30분 가운데 7분쯤이라
merge에서 뺐고, 실패하면 main이 빨강이 되어 다음 PR이 고친다(권하는 안으로 정함 2026-11-12, 총괄). release와
production 게이트는 matrix check로 남는다. 실패를 무시하는(soft-fail) 연결은 없다.
같은 PR이나 같은 브랜치에 새 push가 오면 workflow `concurrency`가 앞 run을 취소한다. Gitea는
앞 run의 대기 중인 job은 언제나, 돌고 있는 job은 `cancel-in-progress`가 참일 때 취소한다.
수동 실행(`workflow_dispatch`)은 ref와 stage마다 group이 따로이고 돌고 있는 run을 취소하지
않는다. 검증과 승격 사이의 release run이 다음 수동 실행에 끊기지 않게 하려는 것이다.
## 기준선 갱신과 새 프로젝트 시작 시 초기화할 기준선
게이트·명령·산출물 수와 게이트 모양 해시를 따로 기록하던 기준선 파일은 2026-11-08에
지웠다(소유자 결정, design-docs `repo-structure/README.md` 3.3절). 계약의 모양은
`scripts/contracts/ci-gates.ts`의 의미 검사(게이트·job·stage 소유와 순서)가 지킨다.
게이트·명령·산출물을 바꾼 뒤에는 `corepack pnpm generate:ci-workflow`와
`corepack pnpm check:ci`를 돌리고 생성된 workflow를 함께 커밋한다. 제거 검증
(`test:*-removal`)은 줄인 계약을 그대로 불러 canonical `check:ci`를 돌린다
(`scripts/lib/removal-fixture.ts`의 `pruneRemovalFixtureCiContract`).
`check:ci:gating`(main 단계 FE-GATE-029)은 `tests/` 아래 테스트 파일(`tests/fixtures` 제외)이 모두 CI 게이트
명령에서 실행되는지 확인한다. 게이트 명령이 닿는 package script의 Vitest 경로와
Playwright 설정의 `testDir`를 모아 비교한다(`scripts/lib/ungated-tests.ts`).
`run-scale-profile.ts <tier>`를 부르는 명령은 그 tier의 Vitest 경로로 센다.
게이트가 돌리지 않는 테스트는 `config/ci/ungated-tests.json`에 이유와 함께 적어야
한다. 게이트가 이미 돌리는 파일을 이 목록에 남겨 두면 실패한다.
package script도 같은 방식으로 확인한다(`scripts/lib/ungated-scripts.ts`).
`check:*`·`verify:*`·`test:*`·`drill:*`·`review:*`·`scan:*` 스크립트는 게이트 명령에서
package script 그래프로 닿거나, 게이트가 이미 돌리는 Vitest 경로만 다시 돌려야
한다. 둘 다 아니면 `config/ci/ungated-scripts.json`에 이유와 함께 적는다. 게이트가
닿는 스크립트를 이 목록에 남겨 두면 실패한다. 두 목록에 남은 항목과 이유는 각
파일에 있다.
규모 테스트는 이렇게 나뉜다(리뷰 0925/11-03, `scripts/scale/run-scale-profile.ts`).
- `check:scale:pr`은 merge gate `FE-GATE-005`에서 돈다. 개수·상한·증가 모양만
검사하므로 CPU가 달라도 결과가 같다. S0~S2 조합 증가 검사가 여기 있다. S0/S1만
재면 모든 workload가 noise floor 아래라 이차 누적을 놓친다. 조합 timing은
산출물(`artifacts/scale/pr/composition-s0-s2.json`)에 기록만 한다.
- `main`·`nightly`·`release` tier는 CI에서 돌지 않는다. 이 tier들은
`baseline-regression`을 포함한다. 이 단계는 `config/scale/benchmark-baseline.json`을
기록한 CPU 모델에서만 timing을 비교하고, 다른 CPU에서는 `incomplete`로 끝난다.
이 tier에만 있는 테스트는 `ungated-tests.json`에, tier를 실행하는 `check:scale:*`
스크립트는 `ungated-scripts.json`에 이유와 함께 남아 있다.
템플릿을 복사해 새 프로젝트를 시작하면 아래 기준선은 템플릿의 값이다. 샘플을
지우거나 구조를 바꾸면 프로젝트 값으로 다시 찍는다.
| 기준선 | 파일 | 갱신 방법 | 검사 위치 |
|---|---|---|---|
| registry 스냅샷과 승인 | `config/contracts/registry-baseline.json`, `registry-baseline.approval.json` | `update:registry-baseline` (`REGISTRY_BASELINE_OWNER`·`_REASON` 필수). 기준선을 새로 찍지 않고 breaking 변경을 유지하려면 `config/contracts/registry-change-evidence.json`에 항목을 추가(`changeId`, 그 변경 뒤 값 `after`(삭제는 생략, 값은 JSON 그대로이고 키·원시값 배열 순서는 상관없다), `versionBump`·`migration`·`compatibilityWindow`·`rollback`·`owner`). 같은 칸을 다시 바꾸면 `after`가 달라 새 항목이 필요하다. 지금 diff의 breaking 변경과 changeId가 맞지 않는 항목이 있으면 게이트가 그 항목을 나열하며 실패한다. `update:registry-baseline`은 새 기준선이 설명하는 항목을 모두 지운다(지운 항목은 git 이력에 남는다) | `scripts/check-registries.ts`의 baseline 비교 |
| 커버리지 모듈 수 하한 | `config/testing/risk-coverage.json`의 `repositoryBaseline` | 직접 수정. 지운 production 모듈 수만큼 줄인다(`scripts/test-sample-removal.ts`가 같은 계산을 한다) | `scripts/lib/risk-coverage.ts` "repository module baseline" |
| 기능 끄기 설정 | `config/runtime/<profile>.json`의 `FEATURE_OVERRIDES` | 직접 수정. 지운 기능의 키를 뺀다(`scripts/test-sample-removal.ts`가 같은 일을 한다) | 실패하는 검사는 없다. 남은 키는 아무것도 끄지 않고, `check:release-admission`(FE-GATE-027)이 `release admission warning: FEATURE_OVERRIDES.<id> … the override does nothing`을, 부팅이 진단 `feature.override.unknown`(warn)을 남긴다(리뷰 0925/09-09) |
| 의존성 목록 | `config/security/dependency-baseline.json`, `dependency-baseline.approval.json` | `update:dependency-baseline` (`DEPENDENCY_BASELINE_OWNER`·`_REASON` 필수) | `scripts/generate-supply-chain.ts` |
계약을 불러올 때, runner가 실행 callback에 들어가기 전에 등록된 명령 항목을 모두
검증한다. 기준은 정본인 루트 package script 그래프와 lifecycle/install 정책이다. 그래서
다른 cwd/workspace의 script로 넘기는 호출, 인자에 따라 동작이 바뀌는 dispatcher, 효과
없는 lifecycle 억제는 사전 검사(preflight)에서 실패한다. 나중의 `check:ci` 명령이 돌지
않는 경우에도 그렇다. npm에서는 이 루트 전용 경계가 명시적
`run`/`run-script` 대상이나 암묵적 `test`/`start`/`stop`/`restart` 대상 뒤의 옵션도
해석한다. `--workspace`, `-w`, `--workspaces`, `--prefix`는 다른 manifest 범위를
가리키므로 실행 전에 거절한다. 처음 나오는 글자 그대로의 `--`가 npm 옵션 해석을 끝낸다.
그 뒤 token은 일반 script 인자다. pnpm과 Yarn은 다르다. 고른 script 이름 뒤의 옵션은 그
script로 넘어간다. cwd/workspace 선택자는 package manager가 script를 고르기 전에 소비하는
위치에 있을 때만 거절한다.
npm 그래프는 명시적 `run`/`run-script` 의존과 암묵적
`start`/`stop`/`restart`/`test` 의존마다, 그 앞뒤에 있는 루트 manifest의
`pre<script>`, `post<script>` hook을 포함한다. hook을 빼는 것은 처음 나오는 글자 그대로의
`--` 앞에서, 순서대로 놓인 npm 옵션이 실제로 적용될 `--ignore-scripts` 값을 모호함 없이
정할 때뿐이다. 값 없는 형태와 명시적으로 참인 형태는 hook을 뺀다. 거짓, 부정, 모순, 잘못된
형태, 구분자 뒤의 형태는 hook을 계속 따라가거나 닫힌 쪽으로 실패한다(fail closed).
token으로 나눈 명령이 npm을 부르면 대소문자와 상관없이 `npm_config_workspace`,
`npm_config_workspaces`, `npm_config_prefix`, `npm_config_userconfig`,
`npm_config_globalconfig` 대입을 거절한다. 직접 대입, basename이 `env`인 정적 경로,
정확한 `command`/`exec` 접두 사슬, 앞선 export, `set -a` 대입은 같은 접두 문법 하나를
쓴다. 허용하는 것은 모형으로 정의한, 범위를 바꾸지 않는 `env -i`, `env -u`,
`env --unset`, `env --` 형태뿐이다. cwd를 바꾸거나 모르는 옵션은 닫힌 쪽으로 실패한다.
동적인 대입 이름, 모형에 없는 환경 변경, npm `--userconfig`/`--globalconfig`, npm 인자
구분자 앞의 따옴표 없는 경로 이름 확장은 거절한다. 게이트 runner는 계약을 불러오거나 실행
callback에 들어가기 전에 물려받은 환경 변수에서도 같은 이름을 검사한다. 그래서 그 이름은
자식 게이트 process에 닿지 못한다.
이 셸 파서(`scripts/lib/package-script-graph.ts`)는 리뷰 0925/12-10에서 줄일 수
있는지 확인했고 남겼다. workflow 설치의 `--ignore-scripts`와
`pnpm-workspace.yaml`의 `allowBuilds`로는 막히지 않는 위험이 있기 때문이다.
첫째, 게이트 명령이 직접 설치를 돈다(`verify:lockfile`, 제거 fixture).
`allowBuilds`는 pnpm의 의존성 build script만 제한한다. 루트 프로젝트의 install
hook과 npm/yarn 설치는 `--ignore-scripts`가 없으면 그대로 돈다. 둘째, 게이트가
부르는 이름이 다른 manifest의 script로 바뀌는 경로다(`--prefix`, `--filter`,
`-C`, npm pre/post hook, `npm_config_*`). 이것은 설치 옵션과 관계가 없다. 이유는
파일 머리 주석에도 있다.
의존 그래프는 아래와 같다.
```text
MERGE_READY
-> RELEASE_READY
-> PROD_PROMOTION_READY
-> FIELD_SLO_READY
DOCUMENTATION_READY (off-chain)
```
`DOCUMENTATION_READY`(`verify:documentation`)가 검사하는 범위와 방법은 `docs/README.md` 5절과
`docs/work/reference/gates.md` 「문서 검사」가 정본이다(코드는 `scripts/verify-documentation-readiness.ts`,
`scripts/lib/docs-system.ts`). 여기에 목록을 다시 적지 않는다(1112/08-07).
`check:architecture`는 Babel parser/Node resolver 기반 `staticImportGraph`를
`artifacts/quality/dependency-report.json`에 기록한다. 규칙은
`.dependency-cruiser.json`에서 읽지만 dependency-cruiser는 실행하지 않는다.
dependency-cruiser 18은 TypeScript 7을 해석하지 못해 0개 모듈을 검사하고
통과했다(리뷰 0925/12-05). TS/TSX의 static, dynamic, type, CommonJS 및 JSDoc import를 검사하고,
로컬 source import에는 실제 TypeScript 확장자를 요구한다. 실행 source나 로컬
specifier에 `.js/.jsx/.mjs/.cjs`가 있거나 unresolved dependency, parse failure,
error-severity layer violation, cycle 또는 지원하지 않는 architecture rule
shape가 하나라도 있으면 gate는 실패한다. resolver, unresolved import, layer
edge와 cycle regression fixture도 같은 명령에서 실행된다.
Gitea workflow는 run ID/attempt, checkout SHA와 ref에서 build/release
식별자를 만들고 최소 `contents: read` 권한만 요청한다. Gate runner는 `HEAD`의
full commit ID와 commit timestamp를 한 번 읽어 `SOURCE_DATE_EPOCH`를 유도한
뒤 workflow의 SHA와 실제 checkout이 일치하는지 확인한다. `CI=true`에서 이
식별자 중 하나라도 없거나 불일치하면 build step 전에 fail-closed하며, build와
release manifest도 같은 build ID, commit SHA, release ID와 timestamp를 가져야
한다.
`release_gate` job은 tag run이면 그 tag 이름(예 `v1.4.0`)을 `RELEASE_TAG`로 준다.
FE-GATE-028이 이 값을 요구한다(`requiresEnvironment`). tag run이 아니면(브랜치에서 수동으로
돌린 release 단계) 값이 비어 게이트가 `missing required environment: RELEASE_TAG`로 실패한다.
Release tier의 `immutable_build`는 `dist`의 hidden `.vite` entries, raw
`pnpm-lock.yaml`, build/module inventory와 local release/security evidence를 한
번 생성해 run ID/attempt로 구분된 archive로 게시한다. Raw lock bytes의 SHA-256은
dependency inventory와 candidate manifest 양쪽의 `lockfileSha256`과 같아야 한다.
Producer는 게시 전에 manifest가 선언한 exact member set과 각 byte digest를
검증하고 archive SHA-256을 job output으로 고정한다. 같은 job은 마지막 단계에서
FE-GATE-015·027의 gate log와 evidence, `scan:dependency-advisories` 기록을 후보와
다른 이름(`immutable-gate-evidence-<run>-<attempt>`)으로 성공·실패와 상관없이
올린다(1105/13-01). 올라가는 것은 그 run에 생긴 파일이다. `ci:gate`는 처음 실패한
명령에서 멈추므로 FE-GATE-027은 막지 않는 advisory 검사를 승인보다 먼저 돌린다.
그래서 승인이 거절된 run에도 advisory 기록이 있다(1106/13-01). FE-GATE-015가
실패하면 FE-GATE-027이 돌지 않으므로 그 run에는 FE-GATE-027의 log와 advisory
기록이 없다. `ci:gate`는 명령 출력을 gate log에만 쓰고 콘솔에는 한 줄만
남기므로, release 단계의 실패 이유는 이 산출물에서 읽는다. 후보 archive의 member
set은 그대로다. Vulnerability/provenance
provider job은 같은 archive를 각각 내려받아 output SHA-256과 exact member set을
확인한 뒤 checkout과 분리된 root에만 추출하고, `CANDIDATE_LOCKFILE_PATH`와
`CANDIDATE_DIST_SHA256`를 외부 command에 전달한다. Provider command 실행 후에는
archive와 추출된 candidate를 다시 검증하고, strict provider JSON과 candidate
digest가 일치할 때만 report를 업로드한다. Promotion은 같은 archive와 두 report를
별도 경로로 내려받고 SHA/member 검증을 마친 뒤 격리된 root에 추출하여 local
evidence를 read-only로 다시 계산하고 Ed25519 signature/digest를 확인한다.
Promotion job에는 build/rebuild command가 없으며 검증한 archive 자체를 변경 없이
그대로 승격한다. Local evidence 관계 검증에 필요한 policy와 verifier source도
archive member로 고정되며, checkout 밖의 격리된 cwd에서도 archive path와 기대
digest만으로 candidate-internal check를 재계산하고 archived secret-scan
policy/rule/SARIF/zero-finding/digest 관계를 검증한다. Archive에 없는 checkout
source를 다시 scan했다고 주장하지 않는다.
Provider baseline은 Gitea 1.26.4 이상과 Gitea Runner 1.0.0 이상이다. Linux
runner에는 실행 가능한 `/usr/bin/bwrap`, `/usr/bin/prlimit`,
`/usr/bin/systemd-run`, `/usr/bin/systemctl`, `bwrap --size` 지원, 활성 user
bus, 254 이상의 systemd user manager, 통합 cgroup v2와 위임된(delegated)
memory/pids/CPU controller가 모두 필요하다. 실행 파일, user manager/version,
trust/archive/path 같은 host-side preflight 실패는 raw report 생성 전에 차단된다.
`bwrap --size` 수용 여부와 실제 delegated controller/limit 값은 owned raw inode를
만든 뒤 scope 안에서만 확정할 수 있으며, 이 단계의 실패는 해당 inode를
identity-bound cleanup하고 fail closed한다.
**비특권 user namespace (1105/12-01).** runner는 비특권 process가 bubblewrap으로
user namespace와 network namespace를 만들 수 있게 허용해야 한다. provider
sandbox는 `bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net`으로
뜬다(`scripts/lib/provider-sandbox-namespaces.ts`). bubblewrap은 setuid가 아니므로
이 옵션마다 비특권 user namespace가 필요하다. 이 조건은 provider job과 merge
게이트 FE-GATE-013(`test:system`의 provider 테스트) 둘 다에 걸린다.
`config/ci/gates.json`의 FE-GATE-013 `hostRequirements`에 같은 조건이 있고,
생성 workflow는 그것을 merge job의 `runs-on` 옆 주석으로 보여 준다. release의
provider job 둘도 같은 조건을 job의 `hostRequirements`로 갖고(계약이 FE-GATE-013과
같은지 본다), 생성 workflow가 그 job의 `runs-on` 옆에 같은 주석을 쓴다.
`scripts/run-and-validate-provider.ts`는 provider를 띄우기 전에 아래 검사와 같은
namespace 점검을 돌아, 이 조건이 없는 runner에서 이름과 host 설정을 대며 멈춘다.
- Ubuntu 23.10부터는 `kernel.apparmor_restrict_unprivileged_userns=1`이
기본이다(24.04도 같다). `/usr/bin/bwrap`에 `userns`를 허용하는 AppArmor
profile이 없으면 bwrap이
`bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`로 끝난다.
- `test:system`은 먼저 `scripts/check-system-test-prerequisites.ts`를 돈다. 이
검사는 provider와 같은 namespace 옵션으로 bwrap에서 `/bin/true`를 한 번
띄운다. 실패하면
"this host does not allow unprivileged user and network namespaces"와 bwrap의
stderr, 위 sysctl 값, 고치는 방법을 적고 exit 1로
멈춘다. 전에는 이 검사가 PASS를 낸 뒤 provider 테스트가 bwrap 원문 오류로
실패했다(2026-11-05 desktop에서 114건 중 18건).
- 고치는 방법은 `scripts/check-system-test-prerequisites.ts`가 실패할 때
출력한다. 호스트의 보안 설정을 바꾸는 일이므로 호스트 소유자가 고른다.
호스트를 바꾸는 설정 파일과 명령은 runner를 만드는 쪽의 인프라 repo가 갖는다.
**이 템플릿이 FE-GATE-013을 돌리는 곳.** 호스트 설정을 바꾸지 않고, 게이트를
일회용 privileged systemd 컨테이너 안에서 돌린다. 계약의 FE-GATE-013
`hostEnvironment: "system-container"`를 보고 생성 workflow와
`scripts/verify.sh`가 `scripts/run-in-system-container.sh`로 게이트를 감싼다.
래퍼는 `config/ci/system-container.Dockerfile`(Ubuntu 24.04, systemd PID 1,
root linger, bubblewrap)로 이미지를 만들고, 작업 트리·git 이력·호출한 쪽의
node와 corepack을 복사해 root로 돌린 뒤 `artifacts/`를 되가져온다. CI에서는
runner의 Docker proxy가 안쪽 dind daemon에 컨테이너를 띄운다.
- root는 호스트의 user namespace 제한을 받지 않는다. 그래서 이 길은 「비특권
runner에서 bwrap userns」 조건 자체를 증명하지 않는다. 그 조건이 필요한
release 단계 provider job은 아직 job 컨테이너에서 돈다.
- runner가 privileged 컨테이너를 막는 설정(rootless dind 등)으로 바뀌면 이
길이 깨진다. 그때는 위 조건을 갖춘 전용 runner(VM 등)로 옮긴다.
각 provider는 고유한 collected user scope에서 실행된다. Supervisor는 실행 전에
실제 cgroup membership과 `memory.max=1073741824`, `memory.swap.max=0`,
`pids.max=64`, `cpu.max="100000 100000"`을 확인한다. 내부 process에는 core 0,
file-size 8,388,607 bytes, open FD 64, CPU 1,200초 상한도 적용된다.
같은 UID 전체에 합산되는 `RLIMIT_NPROC`로 provider별 32개를 보장한다고 주장하지
않으며 aggregate PID authority는 cgroup `TasksMax=64`다.
Bubblewrap는 network namespace를 분리해 완전 offline으로 실행하고 workspace,
verified candidate, `.git` mask, `/tmp`, `/etc`, `/proc`, `/dev`를 read-only로
유지한다. Archive 검증·추출과 sandbox/trust preflight가 끝난 뒤 supervisor가
생성하고 inode를 고정한 정확한 raw report 파일 하나만 read-write bind된다.
주변 `untrusted` directory 전체는 writable이 아니다. 실행 전 또는 provider
실패 시, 그리고 성공적으로 sealed evidence를 게시한 뒤에도 supervisor가 소유한
inode만 atomic quarantine을 거쳐 제거하므로 빈 stale report 없이 재시도할 수 있다.
Provider command와 provider 접두사가 붙은 environment는 크기 상한이 있는 length-prefixed bwrap vector로
`systemd-run` stdin에 전달되어 supervisor/systemd/bwrap wrapper argv나 unit
metadata에 노출되지 않는다. 단, 최종 provider executable의 일반 argv는 같은
UID의 process inspection에 보일 수 있으므로 command 문자열과 인자에 token,
password, private-key material을 넣으면 안 된다. Credential은 반드시 해당 종류의
`VULNERABILITY_PROVIDER_*` 또는 `PROVENANCE_PROVIDER_*` environment로만 전달하고
`*_COMMAND`에는 넣지 않는다. 정상 provider 종료까지 같은 stdin을 parent-liveness
pipe로 열어 두며 supervisor hard death의 EOF를 받은 in-scope wrapper는 provider
process group 전체를 종료하고 dev/inode가 일치하는 raw report만 정리한다.
별도의 trusted guardian child는 provider scope 밖에서 filesystem transaction 전체를
소유한다. Client는 spawn 전에 canonical raw/evidence directory를
`O_DIRECTORY|O_NOFOLLOW`로 열고 identity를 확인한 뒤 provider kind와 nonce에서
canonical raw/final 및 nonce-private raw-staging/sealed-temp exact leaf를 확정한다.
Client가 두 private file을 `O_RDWR|O_CREAT|O_EXCL|O_NOFOLLOW` mode `0600`으로
미리 할당하고 dev/inode를 기록한다. Directory descriptor는 guardian fd 3/4,
private file descriptor는 fd 5/6으로 상속되며 guardian argv에는 Node와 helper
경로만 있다. 최초 canonical v2 frame에는 provider kind, absolute deadline,
32-byte nonce만 전달한다.
Guardian bootstrap은 procfs link를 읽기 전에 fd 5/6을 fstat한다. Procfs pathname은
canonical directory의 exact direct-child grammar를 만족하고 descriptor-relative
lstat이 이미 확보한 fd identity/type/mode/size/link count와 일치할 때만 해당
identity의 cleanup alias가 된다. Guard frame 검증 뒤 raw staging을 fixed raw leaf에
no-overwrite hard link하고 두 alias의 link count 2를 확인한 다음 private alias를
제거하고 raw directory를 sync한다. Canonical raw가 같은 identity와 link count 1로
남은 뒤에만 READY를 응답한다. READY 전 종료 시 client는 pre-spawn raw identity로
raw staging/canonical을, sealed identity로 temp/final을 각각 확인해 일치하는 alias만
정리한다. 현재 canonical pathname을 새 ownership identity로 승격하지 않으므로 외부
file과 concurrent same-kind winner를 보존하면서 같은 workspace를 즉시 재시도할 수
있다. Supervisor는 READY identity와 canonical target도 정확히 확인한다.
검증된 JSON bytes는 pinned temp inode에만 기록하고 `0400` 적용과 file sync를 마친다.
Guardian은 authenticated publish의 size/hash/identity를 재검증하고 같은 directory에서
no-replace `link(temp, final)`, temp unlink, directory sync를 수행한 뒤 PUBLISHED를
응답한다. `GITHUB_OUTPUT` append 이후 commit은 raw inode를 제거하고
`commitPending`으로만 전이하며, 깨끗한 control EOF까지 확인해야 PASS가 된다. 그 전의
EOF, deadline, 잘못된 frame/nonce, commit 뒤 추가 byte 또는 guardian 조기 종료는
identity가 일치하는 raw/temp/final을 모두 정리하고 fail closed한다. Provider wall
timeout 30분에 post-processing 10분을 더한 guardian lease 상한은 40분이다.
Client가 private allocation 뒤 guardian spawn 전에 hard stop되면 empty mode-`0600`
nonce-private leaf만 남을 수 있다. 기록되지 않은 pathname은 ownership 근거가 아니므로
자동 sweeping하지 않는다. 이 private leaf는 fixed raw/final name을 점유하지 않아
same-kind retry를 막지 않는다.
`GITHUB_OUTPUT`은 runner가 소유한 regular file이라는 실행기 계약을 전제로 한다.
Sealing/output I/O의 OS-level cancellation을 보장하지 않는다. Provider scope가 이미
수집된 뒤 guardian이 종료되면 scope-active latch는 늦은 kill을 시작하지 않고 lifecycle
error만 기록한다. 이후 publish/commit의 awaited failure가 identity가 고정된
raw/temp/final fallback을 모두 정리하고 fail closed한다.
Provider stdout/stderr는 credential을 포함할 수 있는 untrusted bytes이므로 CI log로
재전송하거나 보관하지 않고, byte 수만 합산해 1 MiB 상한을 적용한다. Guardian의
stderr/control fd가 닫혀 진단 출력이 `EPIPE`/`EBADF`가 되어도 cleanup 뒤 nonzero
종료는 생략되지 않는다. Provider wall-clock 상한은 30분이다. Wall
timeout, aggregate output 초과, parent-liveness loss, 실행 중 guardian loss는 provider process group을
명시적으로 SIGKILL한다. 일반 command 실패와 FD/CPU RLIMIT 종료는 실제 exit/signal로
systemd completion을 거치며, 모든 경로에서 wrapper 종료와 systemd unit/cgroup
collection을 확인한다. Adapter는 사전에 배치된 offline data와 supervisor candidate binding만
읽어 정확한 report inode에 기록해야 한다. Scope/cgroup limit drift, residual unit,
workspace·host home/toolcache·sealed evidence 접근 의존성은 모두 blocking failure다.
Workflow가 실행하는 action은 `scripts/contracts/ci-gates.ts`의 단일 typed,
runtime-frozen registry에서만 resolve된다. `uses:`에는 repository 별칭, tag,
branch 또는 short SHA를 허용하지 않고 다음 absolute upstream URL과 full 40-hex
commit만 사용한다.
- `https://github.com/actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5`
(`v4.3.1`)
- `https://github.com/actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020`
(`v4.4.0`)
- `https://github.com/ChristopherHX/gitea-upload-artifact@81f940d004763f986ba3582c007fd842dd5cb0d7`
(patched `v4` branch)
- `https://github.com/ChristopherHX/gitea-download-artifact@75635f32b4c1c41c4b3d64e8f85210112ed4c9c7`
(patched `v4` branch)
Gitea 1.22 공식 Actions 문서는 artifact v4 호환 경로로 이
`ChristopherHX` patched upload/download fork를 권고한다. 이 권고는 실제
설치 환경의 호환성을 증명하지 않으므로, 지원 baseline은 계속 Gitea 1.26.4+
및 Gitea Runner 1.0.0+이며 action 변경은 registry, semantic tests, snapshot과
generated workflow를 함께 갱신해야 한다.
이 workflow를 required check로 전환하기 전에 staging instance에서
`permissions`, `gitea.run_attempt`, 위 digest-pinned patched artifact action을
포함한 한 번의 실제 end-to-end provider smoke를 반드시 통과시켜야 한다.
mock/local generation 결과는 required-check enablement evidence가 아니다. 모든 setup step은
`node-version-file: .nvmrc`를 사용하므로 CI Node.js 버전은 `.nvmrc`의 exact
pin과 같다. CI contract는 `.nvmrc`가 full semantic version인지, 모든 job이 이
파일을 사용하는지 함께 검사한다. `ubuntu-latest` runner label은
관리자가 임의 환경에 매핑할 수 있으므로 provenance로 사용하지 않는다. 대신
그 label을 immutable container image에 매핑하고 동일한 image digest를
repository variable `RUNNER_IMAGE_DIGEST`에 설정한다. Workflow는 이 값을
runtime environment의 `CI_RUNNER_IMAGE`로 전달하며, 값이 비어 있으면 모든
gate가 실행 전에 실패한다. Gitea repository variable 이름에는 `CI` prefix를
사용할 수 없으므로 두 이름을 의도적으로 구분한다.
pull request와 `develop` push는 merge 준비 상태(merge readiness)를 평가한다. version
tag는 merge를 평가한 뒤 release 준비 상태를 평가한다. production과 field 평가는 명시적인
workflow dispatch가 있어야 한다. field tier는 28일 표본 기준(threshold) 결정이 기록될
때까지 통과할 수 없다. 문서 준비 상태(documentation readiness)는 범위를 정한 두
diagram이 이미 100/100 `PASS_SCOPED`를 받은 정본 project-note 증거를 쓴다. repo
ledger는 그 증거의 범위와 정본 digest를 보존한다.
모든 job은 실패한 뒤에도 공유 `artifacts/` 트리를 올린다. 보관 기간 숫자는 조직이나
provider가 정할 일로 남긴다. workflow는 일부러 `retention-days`를 지어내지 않는다.
상대적인 최소 보관 기간은 registry에 기록한다. merge 증거는 PR 결정까지, 서로 맞는
release 증거는 다음 release 승격까지, drill 증거는 다음 production 승격까지, field
증거는 집계까지 보관한다.
runbook job은 고정 경로 `artifacts/runbooks/<runbook-id>/record.json`에 쓴다. 바뀌는
release identity는 record 안에 저장한다. 그래서 게이트 증거를 찾는 일이 `RELEASE_ID`의
slash나 그 밖의 provider별 문자에 영향을 받지 않는다. 그러면서도 workflow 산출물은 각자
자기 run 범위에 남는다.
runbook drill(`drill:runbook`, FE-GATE-021..025)은 판정마다 `PASS`, `FAIL`,
`UNVERIFIED` 중 하나로 기록한다(`scripts/drill-runbook.ts`, record schema는
`scripts/contracts/release-artifacts.ts`). `PASS`/`FAIL`은 drill이 빌드된 `dist/`를
대상으로 확인했다는 뜻이다. drill은 `public/`의 placeholder를 읽지 않으므로 빌드가 없으면
실패한다. CI의 production 단계는 다시 빌드하지 않는다. `production_gate`는 promotion
job의 `promoted-release` 산출물을 내려받는다. 그 `release-candidate.tar.gz`를
`immutable_build`의 `archive_sha256`과 대조한 뒤
(`scripts/verify-ci-candidate-archive.ts`) `.release/promoted-release`에 푼다. drill
명령마다 `--release-root .release/promoted-release`를 넘긴다(`config/ci/gates.json`).
CI 계약은 빌드하거나 release root를 빠뜨린 production 게이트 명령을 거절한다
(`scripts/contracts/ci-gates.ts`, 13-03, 1101/13-01). 로컬에서 `--release-root` 없이
돌리면 drill은 로컬 빌드를 검사한다.
hosting 게이트 FE-GATE-019도 `.release/promoted-release`를 읽는다. 그 archive의 `dist`를
검사하고, live 호스트가 후보(candidate)의 `buildId`와 `releaseId`를 담은
`release-manifest.json`을 내주기를 요구한다. 그래서 아직 이전 release를 내주는 호스트는
실패한다(1101/13-01). 같은 run에서 다시 빌드한 것도 같은 이름을 갖는다. 그래서 호스트가
내준 `config.json`도 두 긴급 스위치를 빼고 후보의 것과 같아야 하고, 호스트가 내준
`index.html`도 후보의 진입 스크립트를 가리켜야 한다(1103/13-01). workflow는 스스로
아무것도 배포하지 않는다. `promotion`과 `production_gate` 사이에 `deployment` job이
있다. 이 job이 프로젝트의 배포 슬롯이다. 기본값은 비어 있다. 그러면 job은
`deployed=false`를 보고하고, FE-GATE-019는 호스트를 probe하지 않고 `UNVERIFIED`(exit
3)로 끝나며, production 단계는 닫히지 않는다. 슬롯을 채우려면 제품이 소유한
`config/ci/product-gates.json`에 `deployment`를 넣고
`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": []
}
```
슬롯의 나머지는 템플릿이 생성한다. `promoted-release` 전송물을 내려받고, 후보 digest와
대조해 `.release/promoted-release`에 푼 다음, script를 돌린다. 그 script가
`.release/promoted-release/dist`를 배포한다. `environment`는 `vars.*`와 `secrets.*`
값만 받는다. 템플릿은 이 파일을 비운 채로 내보내고 절대 바꾸지 않는다. 그래서 템플릿
동기화가 이 파일과 부딪히지 않는다. `config/ci/gates.json`은 템플릿의 것으로 남고, 그
계약 기준선은 템플릿 계약만 센다. 두 파일 모두에 슬롯을 채우면 거절한다.
`mergeGates`는 제품 자체 검사를 더한다. 예를 들어 짝 백엔드와의 계약 검사는
`{ "id": "PRODUCT-GATE-001", "name": "backend-contract", "script": "check:backend-contract" }`이다.
ID는 `PRODUCT-GATE-NNN`이다. `FE-GATE-NNN` ID와 그 명령, 산출물, 준비 상태 공식은
템플릿의 것으로 남는다. 각 검사는 `product_merge_gate` job에서 `corepack pnpm <script>`로
돈다. 조건은 merge job들과 같다. 브라우저 없이, `ci:gate`의 게이트 log와 evidence
산출물 없이 돈다. `release_gate`는 merge job들을 기다리듯 그 job도 기다린다. 그래서
제품 게이트가 실패하면 같은 run의 release 빌드, 승격, 배포도 멈춘다(1105/13-02). 제품
게이트가 없으면 workflow는 템플릿의 것 그대로다. pull request merge를 막는 것은 branch의
required check다. 그러니 merge를 막아야 하는 곳에서는 이 job을 required check로 만든다.
`check:ci`는 `package.json`에 없는 script와, `release_gate`가 제품 job을 기다리지 않는
workflow를 거절한다. 그리고 이 script들을 게이트가 돌리는 것으로 센다.
`config/ci/gates.json`에 저장한 슬롯도 같은 계약 규칙을 따른다. 계약이 허용하는 step은
`checkout`, `setup-node`, `frozen-install`, `download`(`promoted-release` 전송물),
`extract`, 그리고 `script`가 package script를 가리키는 마지막 `deploy` step 하나다.
변수는 `immutable_build`의 `CANDIDATE_ARCHIVE_SHA256` digest와 `vars.*`, `secrets.*`
값만 쓸 수 있다. deploy script가 있는 슬롯은 `promoted-release` 전송물만 내려받고, 그
`release-candidate.tar.gz`를 풀고, digest를 묶어야 한다. 그래서 script는 다시 빌드한
것이 아니라 승격한 후보를 배포한다(1103/13-01). `secrets.*` 값은 job이 아니라
`deploy` step에만 넣는다. 그래서 checkout, setup-node, download action은 그 값을 보지
못한다(1103/13-05). `deploy` step은 script가 성공한 뒤에만 `deployed=true`를 쓴다.
이 job은 게이트를 소유하지 않는다. 그래서 슬롯을 채워도 게이트 소유와 계약 기준선은
바뀌지 않는다. 브라우저 boot, live API 트래픽, provider 전환 뒤의 smoke, runbook이
provider 확인이 필요하다고 표시한 것은 모두 `UNVERIFIED`다. `FAIL`이 하나라도 있으면
drill은 `FAIL`(exit 1)이다. 그렇지 않고 `UNVERIFIED`가 하나라도 있으면
`UNVERIFIED`(exit 3)이고, 게이트는 `PASS`가 아니다. 그래서 provider 증거가 없으면
production 단계는 닫히지 않는다. 의도한 결과다. 로컬 drill은 승격한 release를 rollback할
수 있다는 것을 보여 줄 수 없다. FE-GATE-016(`rollback-drill`)은 FE-GATE-025와 같은
FE-RB-005 drill을 돌렸으므로 폐기했다(`scripts/contracts/ci-gates.ts`의
`RETIRED_GATE_IDS`).
브라우저를 쓰는 merge 게이트는 버전을 고정한 Chromium, Firefox, WebKit 엔진을 설치해
실행한다. 그래서 route 동작, reflow, 기본 dialog 동작, theme 유지, 자동 접근성 검사는
Chromium에서만 보는 smoke check가 아니라 엔진 전체에 걸친 계약이 된다.
`FE-GATE-005`의 unit suite에는 client cache/storage의 deterministic contract가
포함된다. `storage-registry.test.ts`는 key별 codec, schema/TTL, 16,384-byte
상한, quota/security/corrupt cleanup과 memory fallback을,
`cross-tab-invalidation.test.ts`는 2,048-byte exact wire, topic/release epoch,
self/duplicate/out-of-order/gap, BroadcastChannel → localStorage → local-only
degrade와 cleanup을 검증한다. `tanstack-cache-coordinator.test.ts`는 topic을
local namespace로만 resolve하고 query key/data를 wire에 보내지 않으며 mutation
중 remote hint를 coalesce하는지 검증한다. 결과는 기존
`artifacts/tests/unit.xml`과 coverage evidence에 포함된다.
`FE-GATE-006`과 runtime adapter unit은
`QueryInvalidationProvider`/coordinator가 실제 production provider tree와
bootstrap에 존재하고 browser capability getter가 실패해도 boot가
`DEGRADED_LOCAL_ONLY`로 계속되는지 확인한다.
`FE-GATE-008`의 `test:browser-capabilities` suite는 File/Blob, 브라우저 기본 file
input, IndexedDB, OPFS, Cache Storage와 StorageManager의 reference runtime을
Vite dev origin의 실제 browser API에 연결한다. API가 없는 engine에서는 skip하지 않고
adapter의 명시적인 `UNSUPPORTED` fallback을 검증한다. 생성한 database, OPFS
namespace와 owned cache는 각 test가 자신이 만든 opaque namespace만 정리한다.
`FE-GATE-010`은 application/domain/presentation에서 raw browser storage와
picker global 접근을 막고, 선택되지 않은 reference runtime을 bootstrap이나
installed feature가 import하는 것도 거절한다. catalog의
`referenceRuntime.sourceRoots`와 conformance script가 실제로 존재해야 하며,
`productionComposition`은 project capability 결정 전까지 `false`다. 같은
gate의 realtime source/fixture 검사는 native SSE/WebSocket/Web Push API가
소유 adapter 밖으로 새는 것, presentation timer owner, 미선택 runtime의
bootstrap/installed-feature 조합을 차단한다. optional recipe source gate는
uncomposed runtime 전체를 tree-shaking 없이 합성해 catalog의 gzip 예산도
blocking으로 검증한다.
`FE-GATE-030`(main 단계)은 reference runtime source·전용 test·catalog metadata를 제거한
임시 repository에서도 base typecheck, architecture, test, build가 통과하는지
검증해 skeleton의 선택성을 유지한다. browser file/storage와 realtime runtime은
각각 독립 removal fixture와 JUnit evidence를 가지며, realtime fixture는 공통
event authority, SSE, WebSocket, 상한 있는(bounded) Polling, Web Push의 source와 공개 export,
전용 boundary script를 제거한 뒤 base gate를 다시 실행한다.
같은 `FE-GATE-010`의 `FE-REG-QUERY` governance는 installed query마다
namespace, serialization/identity, invalidation topic, version,
`crossContext: "invalidate-only"`와 `persistence: "disabled"`를 요구한다.
따라서 cross-tab invalidation은 조립됐지만 query persistence와 기존 IndexedDB
reference runtime은 계속 미조립이다.
현재 `FE-GATE-008` browser-capability suite에는 실제 두 page의
BroadcastChannel/localStorage fallback scenario가 아직 없다. unit fake 통과를
native multi-tab promotion evidence로 간주하지 않는다. 이 gap은
[클라이언트 캐시·브라우저 저장소 플랫폼 설계](../design/2026-07-28-client-cache-and-storage-design.md)의
완료 기준에 미완료로 남아 있다. 현재 장애 분류와 안전한 local-only 복구 절차는
[클라이언트 캐시와 Web Storage 복구](./client-cache-and-storage-recovery.md)를
따른다.
상위 tier가 요구하는 repository 변수는 아래와 같다.
- `RUNNER_IMAGE_DIGEST`: `ubuntu-latest` runner label이 쓰는, 바꿀 수 없는 job container
image의 digest. workflow는 이 값을 게이트에 `CI_RUNNER_IMAGE`로 넘긴다(모든 tier가
요구한다)
- `HOSTING_BASE_URL`: 배포된 승격 release의 live 헤더 검증용(FE-GATE-019, production
단계). 없으면 게이트는 실패한다. 로컬 fixture 결과는 `UNVERIFIED`다.
`deployment` job이 release를 배포했을 때만 probe한다
- `APP_PROFILE`: release 후보를 빌드할 runtime profile(`local`, `development`,
`staging`, `production`;
`scripts/generate-runtime-config.ts`). 설정하지 않으면 `local`로 빌드한다. 빈 값이면
빌드가 실패한다.
- `RELEASE_TARGET`: FE-GATE-027이 후보를 승인해 들여보낼 환경
(`scripts/check-release-admission.ts`). 기본값이 없다. immutable_build job은
FE-GATE-015를 돌린 뒤 FE-GATE-027을 돌린다. FE-GATE-027은 `APP_PROFILE`이 설정돼 있고
`RELEASE_TARGET`과 다르면 후보를 거절한다. 둘 다 repository 전체 변수이므로 release마다
함께 설정한다.
FE-GATE-027은 `scan:dependency-advisories`를 먼저 돌리고 승인(admission)을 그 뒤에
돌린다(1103/13-03, 1106/13-01). 이 scan은 lockfile에 대한 registry의 advisory
report(pnpm의 audit 명령에 `--json`)에
`config/security/vulnerability-policy.json`과 그 예외를 적용한다. 결과는 게이트 log와
`artifacts/security/dependency-advisories.json`에 쓴다. 결과는 `PASS`,
`POLICY_VIOLATION`(production 승격이 거절할 내용과 그 발견 사항),
`UNVERIFIED`(registry 없음) 중 하나다. 이 scan은 게이트를 실패시키지 않는다. 코드가
그대로여도 advisory 데이터베이스가 바뀌면 release가 깨지기 때문이다. 승격은 여전히
vulnerability provider의 서명된 판정이 정한다.
job 콘솔은 게이트마다 PASS/FAIL 한 줄만 보여 준다. 그래서 immutable_build job은 job의
성공·실패와 상관없이 두 게이트의 log와 evidence, 이 기록을 run 산출물
`immutable-gate-evidence-<run>-<attempt>`로 올린다(1105/13-01). 이 산출물에는 그
run이 만든 파일이 들어 있다. `ci:gate`는 처음 실패한 명령에서 멈추고, scan은 승인보다
먼저 돈다. 그래서 승인이 거절된 run에도 advisory 기록이 있다. FE-GATE-015가 실패하면
FE-GATE-027은 돌지 않는다. 그래서 그 run에는 FE-GATE-027의 log도 기록도 없다.
FE-GATE-015나 FE-GATE-027이 실패한 이유와 advisory 상태는 이 산출물에서 읽는다.
Renovate runner를 붙이면 `renovate.json`이 보안 업데이트 PR을 연다. 의존성 업데이트는
같은 변경에서 의존성 기준선을 다시 승인한다
(`update:dependency-baseline`).
- `FIELD_WEB_VITALS_INPUT`: 개인정보 검토를 통과한 field 표본 문서
- `MIN_ELIGIBLE_SAMPLES`: 기준선 결정 뒤에 설정한다
- `VULNERABILITY_PROVIDER_COMMAND`, `PROVENANCE_PROVIDER_COMMAND`: 따로 운영하는
scanner와 attestor 명령
- `VULNERABILITY_PUBLIC_KEY_PATH`, `VULNERABILITY_KEY_ID`,
`PROVENANCE_PUBLIC_KEY_PATH`, `PROVENANCE_KEY_ID`: 따로 관리하는 신뢰할 수 있는
Ed25519 검증 자료
`scan:dependency-advisories`가 이 lockfile에 대해 보고한, 정책의 `high` 이상 advisory는
아래와 같다. 2026-11-04에 확인했다(리뷰 1103/13-03). 2026-12-04까지 또는 아래 업데이트를
할 때 다시 확인한다. 개발 전용 의존성(storybook, vite, vitest, undici, brace-expansion,
nanoid, source-map-js)은 선언한 범위 안에서 업데이트해서 없어졌다.
| Advisory | 패키지 | 고친 버전 | 아직 업데이트하지 않은 이유 |
|---|---|---|---|
| GHSA-mrhx-c7xc-m3w5 (high) | `zod`(production. 지금 버전은 `package.json`) | 4.6.6 | production 직접 의존성을 올리려면 `config/security/dependency-change-evidence.json` 항목이 필요하고, 그 항목의 reviewer는 owner가 아니어야 한다. 고친 버전 이상으로 올리면 초기 JavaScript가 gzip으로 약 7 KB 늘어 번들 예산을 넘는다(2026-11-04에 4.6.7로 잰 값). 그래서 업데이트에는 예산 결정도 필요하다. 앱은 HTTP 본문을 바이트 상한을 두고 읽는다. 그래서 이 advisory가 필요로 하는 큰 collection 입력이 좁아진다(리뷰 추정) |
| GHSA-qwww-vcr4-c8h2 (high) | `react-router`, `react-router-dom`을 거쳐 들어옴(production. 지금 버전은 `pnpm-lock.yaml`) | 7.18.2 | 같은 evidence 규칙을 따른다. 이 advisory는 RSC 모드에 관한 것이다. browser router를 쓰는 이 SPA는 RSC 모드를 쓰지 않는다(리뷰 추정, 확인하지 않음). 7.18.5는 초기 JavaScript를 약 470 B 늘린다 |
두 provider role은 서로 다른 key ID뿐 아니라 canonical DER-SPKI public-key bytes도
사용해야 한다. 동일 key를 서로 다른 ID로 재등록한 구성도 finalizer가 거절한다.
외부 provider 명령, report, trust 경로, key ID 중 하나라도 없으면 승격은
`FAIL_UNVERIFIED`로 막힌 채 남는다. 로컬에서 생성하거나 복원하는 대체 경로(fallback)는
없다.
provider 명령은 각각 supervisor가 묶어 준 값으로 엄격한 provider evidence v2를 원자적으로
내보내야 한다. 묶는 값은 evidence 종류, 발급·만료 시각, run ID/attempt,
`PROVIDER_INVOCATION_NONCE`, source identity, 후보 digest, key ID, DER-SPKI key
fingerprint다. 승격은 두 supervisor job의 output을 `VULNERABILITY_INVOCATION_NONCE`와
`PROVENANCE_INVOCATION_NONCE`로 받는다. 이 값을 상수나 provider report에서 읽은 값으로
바꾸지 않는다.
Promotion verification/staging step과 promoted-release upload action 사이에는
어떤 step도 둘 수 없고 upload에는 `if: always()`를 사용할 수 없다. 이 인접성은
실패한 검증의 publication을 막지만 staging path를 upload action에
cryptographically hand off하지는 않는다. 따라서 promotion runner는 trusted,
exclusive, single-tenant여야 하고 staging step 종료부터 바로 다음 upload action이
파일을 여는 시점까지 같은 UID로 실행되는 provider command나 다른 process가
살아남지 않는다는 운영 가정을 만족해야 한다. 업로드된 artifact의 downstream
consumer도 artifact service나 transfer action을 신뢰 경계 밖으로 보고, candidate
manifest와 signed provider evidence에 바인딩된 digest를 다운로드 후 다시
검증해야 한다. 현재 producer-side adjacency 자체는 consumer-side digest
revalidation을 대신하지 않는다.
Promotion job에는 job-level `if`가 없다. 기본 `needs` 성공 의미론으로 immutable
build, vulnerability provider, provenance provider 세 job이 모두 성공해야 하며,
`always()`나 `cancelled()`로 cancellation을 덮어쓰지 않는다. Bare `always()`는
step cleanup에만 사용된다. 다만 cancellation 시 cleanup 실행 여부는 workflow
정적 타입이나 단위 테스트로 증명하지 않았으며 runner/native smoke에서 확인해야
하는 신뢰 경계다.
Finalizer output은 `RUNNER_TEMP` 아래 random private directory이며 exact-five
upload는 `${{ steps.finalize.outputs.staging_root }}` 아래 다음 다섯 canonical
pathname만 사용한다: `release-candidate.tar.gz`, `vulnerability-report.json`,
`provenance-attestation.json`, `provider-verification.json`,
`promotion-verification.json`. 바로 다음
`always()` cleanup은 staging path/token, runner-temp device/inode와 staging-leaf
device/inode 여섯 output을 모두 요구한다. cleanup은 pin한 leaf descriptor에서
exact-five name만 unlink하고 non-recursive `rmdir`만 사용하므로 교체된 directory나
canary tree를 recursive 삭제하지 않는다. stable `.release/promoted-staging`
directory를 만들거나 재사용하지 않는다. exact five는 captured archive 한 개,
captured report 두 개와 process 안에서 생성한 provider/promotion verification v3
두 개이며 promotion
record는 provider 기록, 로컬 평가(local assessment), report hash와 run/source/candidate/
nonces/key identities/trust-policy hash 및 signed `secretScanAttestation`을 함께
bind한다. 이 attestation은 PASS와 local-assessment/source-set/policy/SARIF/
scan-input digest를 포함한다. Supervisor/finalizer는 captured archive에서 기대
tuple을 유도해 exact equality를 확인하지만, 실제로 같은 source-set 전체를
독립 스캔하고 forged empty SARIF에 서명하지 않을 책임은 trusted vulnerability
provider에 있다. Staging은 restrictive
umask와 무관하게 directory `0700`, file `0400`을 강제하고, 모든 write 뒤 live
time으로 exact-five signature/freshness를 다시 확인한 뒤에만 output을 공개한다.
Descriptor-relative 정리는 ancestor/leaf 교체와 symlink를 fail-closed로 처리하지만
upload action의 same-UID pathname reopen 또는 atomic
`renameat2` handoff를 보장하지 않는다. staging Gitea smoke/native adapter 확인
전에는 그 경계를 닫았다고 보고하지 않는다. 실제 smoke는 exact-five
upload-download와, 성공·검증 실패·upload 실패·취소 각각의
cleanup을 관찰해야 한다. 현재 repository에는 native uploader나 `renameat2`
보장이 없다.
또한 portable Node의 `mkdir`와 최초 pathname `lstat`는 atomic하지 않다. 구현은
mkdir 직후 metadata를 저장하고 이후 `O_DIRECTORY|O_NOFOLLOW` descriptor의
device/inode와 비교한 뒤에만 permission을 바꾸지만, 최초 lstat보다 앞서 성공한
malicious same-UID 교체는 native/privilege 경계로 남는다. 따라서 `RUNNER_TEMP`
private `0700` ancestor와 exclusive single-tenant runner가 필수다.
실패 cleanup도 created device/inode와 opened descriptor가 일치한 뒤에만 활성화된다.
불일치 descriptor는 close만 수행하며 현재 visible replacement pathname은 unlink나
`rmdir`하지 않는다. 공격자가 original directory를 다른 이름이나 parent 밖으로
이동한 경우 portable Node parent scan으로 안전하게 회수할 수 없으므로, 공격자를
배제한 trusted runner/native cleanup 또는 격리된 test fixture가 잔여 directory를
후처리해야 한다.
branch 보호 설정은 각 `FE-GATE-* / <name>` check를 선언한 tier에 맞게 required로 표시해야
한다. 이 repo는 파일을 커밋하는 것으로 서버 쪽 보호 설정을 바꿀 수 없다.