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
문제: #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.
630 lines
50 KiB
Markdown
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는 파일을 커밋하는 것으로 서버 쪽 보호 설정을 바꿀 수 없다.
|