ci(gates): merge job 셋이 의존성 캐시에서 설치를 시작하고 main만 저장한다 #41

Merged
donghyeon.kang merged 2 commits from donghyeon.kang/ci/merge-dependency-cache AGit into main 2026-11-13 01:39:44 +00:00
Owner

무엇을, 왜

merge 25분 목표에 0.8분 모자랐다(run 169 25.8분). merge job 셋은 runner의 새 컨테이너에서 매번 Node(GitHub 다운로드), corepack의 pnpm, 패키지 404개를 받고, pnpm 11은 lockfile 542개 항목의 공급망 정책을 레지스트리에 물어 검증한다. run 169에서 job마다 setup-node 1118초, 설치 1229초였고, 설치 시간의 대부분은 정책 검증의 메타데이터 요청이었다(10.1~27.9초). FE-GATE-013의 시스템 컨테이너는 같은 설치를 한 번 더 한다.

worker를 늘리지 않고 이 반복 내려받기를 없앤다(권하는 안으로 정함 2026-11-13, 총괄: 의존성 캐시는 merge job만, 공급망 증거 job은 매번 새로 설치).

고른 방법과 버린 대안

  • job 단계 dependency-cache: setup-node 앞에서 Node toolcache와 /tmp/fe-dependency-cache(corepack, pnpm store, pnpm 메타데이터 캐시)를 .nvmrc·pnpm-lock.yaml 해시 키로 복원한다(restore-keys로 앞 항목도).
  • 저장은 main run만 한다(actions/cache, refs/heads/main 조건). 그 밖의 ref(PR)는 actions/cache/restore로 main 항목을 같은 키로 읽기만 한다. restore 액션에는 저장하는 post 단계가 없다. pin은 짝 백엔드 캐시와 같은 actions/cache v4.3.0.
  • job env COREPACK_HOME·PNPM_CONFIG_STORE_DIR·PNPM_CONFIG_CACHE_DIR로 job의 모든 pnpm 호출이 같은 곳을 본다. frozen install 단계는 그대로이고 캐시와 관계없이 돈다.
  • scripts/run-in-system-container.sh는 그 env가 있으면 store와 메타데이터 캐시를 같은 경로로 컨테이너에 넘긴다. env가 없으면(desktop) 지금과 같다.
  • 계약: merge job 셋만 이 단계를 가진다(release·promotion·provider·main job은 거절, 단계 순서 고정). 그 env를 job이 따로 묶어도 거절한다. 키 입력은 config/repository-layout.json의 새 집합 dependency-cache-key에서 고른다.
  • 버린 대안:
    • CI 이미지에 의존성을 굽기: 레지스트리 쓰기 토큰이 든다.
    • 브랜치 run도 저장하기: pnpm은 같은 lockfile의 공급망 검증 기록이 캐시에 있으면 다시 검증하지 않는다(「verified 2s ago」). 브랜치가 쓴 항목은 main의 검증을 건너뛰게 할 수 있다.
    • cache-hit이면 설치를 건너뛰기: 결과가 캐시 상태에 달린다.
    • apt 글꼴 캐시: 캐시가 없을 때 새 패키지 버전이 깔려 시각 결과가 달라질 수 있다.

위험과 영향

  • 이 PR의 run은 빈 캐시로 시작한다(main이 아직 저장하지 않음). 효과는 병합 뒤 main push run이 저장하고, 그다음 PR run이 hit할 때 나온다.
  • runner 캐시 저장소(5GB, platform-core infrastructure/ci/gitea-runner/config.yaml)는 짝 백엔드와 같이 쓴다. 항목 하나는 압축 전 약 0.7GB이고 lockfile이 바뀔 때마다 새 항목이 생긴다.
  • Node toolcache 경로(/opt/hostedtoolcache)가 job 이미지와 다르면 그 부분만 효과가 없고 setup-node가 내려받는다.
  • 다운스트림: runner에 cache 서버가 없으면 복원 단계가 경고만 내고 설치는 그대로 돈다(CHANGELOG 「먼저 할 일」).

검증

  • desktop 설치 실험(같은 lockfile, 새 폴더, /tmp/claude-gates/w2fe2-cachex/): 빈 캐시 13.9·17.2초, 캐시 있음 1.6초, store 40개·메타데이터 40개를 망가뜨린 캐시 3.6초(27개만 다시 받음). 다섯 번 모두 node_modules 트리 해시가 같다.
  • FE-GATE-013 흐름을 캐시 env로 재현: 캐시 설치 2.6초, 시스템 컨테이너 안 설치 1.5초(Recreating node_modules 없음, 지금은 31.3초).
  • RED: 계약·생성기를 둔 채 gates.json에서 캐시 단계를 빼면 새 시험 실패. 키 입력을 코드에 직접 적은 첫 판은 repository-layout R2 시험이 잡았다. GREEN: repository-layout·ci-workflow-generation 456개 통과, check:ci·check:types·eslint·verify:documentation rc=0.
  • desktop CI=true scripts/verify.sh merge(트리 0f927214 = main ee47480c + 이 PR): 14개 중 13개 rc=0, status-after 0줄. FE-GATE-008은 Firefox tests/e2e/preload-use.spec.ts:111 하나가 첫 goto 뒤 h1을 5초 안에 못 봐 실패(183개 중 182개 통과). 이 PR은 앱·e2e를 건드리지 않고, 같은 증상이 공유 노트 r9-fe-fix-plan.md 「e2e 첫 렌더가 5초를 넘긴 일」에 열려 있다. 로그 /tmp/claude-gates/w2fe2-cache-merge3/.
  • 지금 merge 단계 시간(캐시 없음): run 169 25.8분, 192 24.6분, 219 22.9분.
  • runner: 이 PR run(빈 캐시)과, 병합 뒤 main push run(저장) → 다음 PR run(hit)으로 merge 단계 시간을 잰다.

리뷰어가 볼 곳

  • scripts/contracts/ci-gates.ts의 DEPENDENCY_CACHE와 merge-only·env 검사.
  • scripts/generate-ci-workflow.ts의 dependency-cache 렌더링(main 저장 / 그 밖 복원만).
  • scripts/run-in-system-container.sh의 pnpm 폴더 전달.
  • .gitea/workflows/quality-gates.yml은 생성 파일이다.

관련

  • 결정 색인 docs/work/reference/decisions.md 「의존성 캐시는 merge job만」, 운영 docs/operations/ci-quality-gates.md merge 단락.
  • 짝 백엔드의 같은 규칙: .gitea/actions/setup-java-gradle/action.yml, .gitea/actions/trivy-db-cache/action.yml.
## 무엇을, 왜 merge 25분 목표에 0.8분 모자랐다(run 169 25.8분). merge job 셋은 runner의 새 컨테이너에서 매번 Node(GitHub 다운로드), corepack의 pnpm, 패키지 404개를 받고, pnpm 11은 lockfile 542개 항목의 공급망 정책을 레지스트리에 물어 검증한다. run 169에서 job마다 setup-node 11~18초, 설치 12~29초였고, 설치 시간의 대부분은 정책 검증의 메타데이터 요청이었다(10.1~27.9초). FE-GATE-013의 시스템 컨테이너는 같은 설치를 한 번 더 한다. worker를 늘리지 않고 이 반복 내려받기를 없앤다(권하는 안으로 정함 2026-11-13, 총괄: 의존성 캐시는 merge job만, 공급망 증거 job은 매번 새로 설치). ## 고른 방법과 버린 대안 - job 단계 `dependency-cache`: setup-node 앞에서 Node toolcache와 `/tmp/fe-dependency-cache`(corepack, pnpm store, pnpm 메타데이터 캐시)를 `.nvmrc`·`pnpm-lock.yaml` 해시 키로 복원한다(restore-keys로 앞 항목도). - 저장은 main run만 한다(actions/cache, `refs/heads/main` 조건). 그 밖의 ref(PR)는 actions/cache/restore로 main 항목을 같은 키로 **읽기만** 한다. restore 액션에는 저장하는 post 단계가 없다. pin은 짝 백엔드 캐시와 같은 actions/cache v4.3.0. - job env `COREPACK_HOME`·`PNPM_CONFIG_STORE_DIR`·`PNPM_CONFIG_CACHE_DIR`로 job의 모든 pnpm 호출이 같은 곳을 본다. frozen install 단계는 그대로이고 캐시와 관계없이 돈다. - `scripts/run-in-system-container.sh`는 그 env가 있으면 store와 메타데이터 캐시를 같은 경로로 컨테이너에 넘긴다. env가 없으면(desktop) 지금과 같다. - 계약: merge job 셋만 이 단계를 가진다(release·promotion·provider·main job은 거절, 단계 순서 고정). 그 env를 job이 따로 묶어도 거절한다. 키 입력은 `config/repository-layout.json`의 새 집합 `dependency-cache-key`에서 고른다. - 버린 대안: - CI 이미지에 의존성을 굽기: 레지스트리 쓰기 토큰이 든다. - 브랜치 run도 저장하기: pnpm은 같은 lockfile의 공급망 검증 기록이 캐시에 있으면 다시 검증하지 않는다(「verified 2s ago」). 브랜치가 쓴 항목은 main의 검증을 건너뛰게 할 수 있다. - `cache-hit`이면 설치를 건너뛰기: 결과가 캐시 상태에 달린다. - apt 글꼴 캐시: 캐시가 없을 때 새 패키지 버전이 깔려 시각 결과가 달라질 수 있다. ## 위험과 영향 - 이 PR의 run은 빈 캐시로 시작한다(main이 아직 저장하지 않음). 효과는 병합 뒤 main push run이 저장하고, 그다음 PR run이 hit할 때 나온다. - runner 캐시 저장소(5GB, platform-core `infrastructure/ci/gitea-runner/config.yaml`)는 짝 백엔드와 같이 쓴다. 항목 하나는 압축 전 약 0.7GB이고 lockfile이 바뀔 때마다 새 항목이 생긴다. - Node toolcache 경로(`/opt/hostedtoolcache`)가 job 이미지와 다르면 그 부분만 효과가 없고 setup-node가 내려받는다. - 다운스트림: runner에 cache 서버가 없으면 복원 단계가 경고만 내고 설치는 그대로 돈다(CHANGELOG 「먼저 할 일」). ## 검증 - desktop 설치 실험(같은 lockfile, 새 폴더, `/tmp/claude-gates/w2fe2-cachex/`): 빈 캐시 13.9·17.2초, 캐시 있음 1.6초, store 40개·메타데이터 40개를 망가뜨린 캐시 3.6초(27개만 다시 받음). 다섯 번 모두 node_modules 트리 해시가 같다. - FE-GATE-013 흐름을 캐시 env로 재현: 캐시 설치 2.6초, 시스템 컨테이너 안 설치 1.5초(`Recreating node_modules` 없음, 지금은 31.3초). - RED: 계약·생성기를 둔 채 gates.json에서 캐시 단계를 빼면 새 시험 실패. 키 입력을 코드에 직접 적은 첫 판은 repository-layout R2 시험이 잡았다. GREEN: repository-layout·ci-workflow-generation 456개 통과, check:ci·check:types·eslint·verify:documentation rc=0. - desktop `CI=true scripts/verify.sh merge`(트리 0f927214 = main ee47480c + 이 PR): 14개 중 13개 rc=0, status-after 0줄. FE-GATE-008은 Firefox `tests/e2e/preload-use.spec.ts:111` 하나가 첫 `goto` 뒤 h1을 5초 안에 못 봐 실패(183개 중 182개 통과). 이 PR은 앱·e2e를 건드리지 않고, 같은 증상이 공유 노트 `r9-fe-fix-plan.md` 「e2e 첫 렌더가 5초를 넘긴 일」에 열려 있다. 로그 `/tmp/claude-gates/w2fe2-cache-merge3/`. - 지금 merge 단계 시간(캐시 없음): run 169 25.8분, 192 24.6분, 219 22.9분. - runner: 이 PR run(빈 캐시)과, 병합 뒤 main push run(저장) → 다음 PR run(hit)으로 merge 단계 시간을 잰다. ## 리뷰어가 볼 곳 - `scripts/contracts/ci-gates.ts`의 `DEPENDENCY_CACHE`와 merge-only·env 검사. - `scripts/generate-ci-workflow.ts`의 `dependency-cache` 렌더링(main 저장 / 그 밖 복원만). - `scripts/run-in-system-container.sh`의 pnpm 폴더 전달. - `.gitea/workflows/quality-gates.yml`은 생성 파일이다. ## 관련 - 결정 색인 `docs/work/reference/decisions.md` 「의존성 캐시는 merge job만」, 운영 `docs/operations/ci-quality-gates.md` merge 단락. - 짝 백엔드의 같은 규칙: `.gitea/actions/setup-java-gradle/action.yml`, `.gitea/actions/trivy-db-cache/action.yml`.
donghyeon.kang added 2 commits 2026-11-13 00:19:58 +00:00
문제: merge job 셋은 runner의 새 컨테이너에서 매번 Node(GitHub
다운로드), corepack의 pnpm, 패키지 404개를 내려받고, pnpm 11은 lockfile
542개 항목의 공급망 정책을 레지스트리에 물어 검증한다. run 169에서 job마다
setup-node 11~18초, 설치 12~29초였고 설치 시간의 대부분은 정책 검증의
메타데이터 요청이었다(10.1~27.9초). FE-GATE-013의 시스템 컨테이너는 같은
설치를 한 번 더 한다. merge 25분 목표에 0.8분 모자랐다.

고친 것(권하는 안으로 정함 2026-11-13, 총괄):
- job 단계 `dependency-cache`를 더한다. setup-node 앞에서 Node toolcache와
  `/tmp/fe-dependency-cache`(corepack, pnpm store, pnpm 메타데이터 캐시)를
  `.nvmrc`·`pnpm-lock.yaml` 해시 키로 복원한다. main run은 actions/cache로
  복원·저장하고, 그 밖의 ref는 actions/cache/restore로 복원만 한다. pin은
  짝 백엔드의 JDK·Gradle·Trivy 캐시와 같다(v4.3.0).
- 생성기가 그 job에 `COREPACK_HOME`·`PNPM_CONFIG_STORE_DIR`·
  `PNPM_CONFIG_CACHE_DIR`를 주어 job의 모든 pnpm 호출이 같은 곳을 본다.
  frozen install 단계는 그대로이고 캐시와 관계없이 돈다.
- PR run은 main이 저장한 항목을 같은 키로 읽기만 한다. 저장할 수 있는
  actions/cache 단계는 `refs/heads/main` 조건 아래에만 있고, 그 밖의 ref가
  타는 actions/cache/restore에는 저장하는 post 단계가 없다(시험으로 고정).
- 계약: merge job 셋만 이 단계를 가진다(release·promotion·provider·main
  job은 거절, 단계 순서 고정에 반영). 그 env를 job이 따로 묶으면 거절한다.
  키 입력은 `config/repository-layout.json`의 새 집합
  `dependency-cache-key`(`.nvmrc`, `pnpm-lock.yaml`)에서 고른다.
- `scripts/run-in-system-container.sh`가 그 env가 있으면 store와 메타데이터
  캐시를 같은 경로로 컨테이너에 넘긴다. 없으면(desktop) 지금과 같다.
- 결정 색인, ci-quality-gates.md, O1 출처 문구를 총괄이 정한 말로 맞춘다.

버린 대안:
- CI 이미지에 의존성 굽기: 레지스트리 쓰기 토큰이 든다.
- 브랜치 run도 저장하기: 캐시 항목은 다음 run이 믿는 입력이다. pnpm은
  같은 lockfile의 공급망 검증 기록이 캐시에 있으면 다시 검증하지 않으므로,
  브랜치가 쓴 항목이 main의 검증을 건너뛰게 할 수 있다.
- `cache-hit`일 때 설치를 건너뛰기: 결과가 캐시 상태에 달린다.
- apt 글꼴 캐시: 캐시가 없을 때 새 패키지 버전이 깔려 시각 결과가 달라질
  수 있다.

위험·한계:
- PR run은 main이 같은 키(또는 restore-keys로 앞 항목)를 저장한 뒤에야
  hit한다. 이 PR 자신의 run은 비어서 시작한다.
- runner 캐시 저장소(5GB)는 짝 백엔드와 같이 쓴다. 항목 하나는 Node·store·
  메타데이터로 압축 전 약 0.7GB다. lockfile이 바뀔 때마다 새 항목이 생긴다.
- Node toolcache 경로(`/opt/hostedtoolcache`)가 job 이미지와 다르면 그
  부분만 효과가 없고 setup-node가 내려받는다.

검증(desktop):
- 설치 실험(같은 lockfile, 새 폴더): 빈 캐시 13.9·17.2초, 캐시 있음 1.6초,
  store 파일 40개·메타데이터 40개를 망가뜨린 캐시 3.6초(27개만 다시 받음).
  다섯 번 모두 node_modules 트리 해시가 같다. pnpm 11은 대문자
  `PNPM_CONFIG_STORE_DIR`·`PNPM_CONFIG_CACHE_DIR`를 읽는다.
- FE-GATE-013 흐름을 캐시 env로 재현: 빈 캐시 설치 13.7초, 캐시 설치
  2.6초, 시스템 컨테이너 안 설치 1.5초(`Recreating node_modules` 없음, 지금은
  31.3초). 그 실행의 FE-GATE-013은 provider 묶음 시험 하나가 손 timeout
  30초에 걸려 실패했다(캐시와 무관, PR #39가 고치는 문제).
- RED: 계약·생성기를 둔 채 gates.json에서 캐시 단계를 빼면 새 시험 6개
  실패. 키 입력을 코드에 직접 적은 첫 판은 repository-layout R2 시험이
  잡았다. GREEN: repository-layout·ci-workflow-generation 456개 통과,
  check:ci·check:types·eslint rc=0, verify:documentation rc=0, 노트북
  `scripts/verify.sh docs` OK.
docs(changelog): merge job 의존성 캐시를 미출시 절에 적는다
frontend-quality-gates / merge / static checks (pull_request) Successful in 1m53s
frontend-quality-gates / merge / tests (pull_request) Successful in 12m19s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 6m4s
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
bbe434ed29
merge job 셋에 의존성 캐시를 더한 일과, 다운스트림이 자기 runner의
캐시 서버·크기 상한을 확인할 일을 적는다.
donghyeon.kang merged commit 9068faf227 into main 2026-11-13 01:39:44 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/clean-architecture-frontend-template#41