Files
DongHyeonka 3b71a3ca32 docs(security): 공개 경로 스냅숏 검사의 설명을 넓어진 범위에 맞춘다
공개 경로 스냅숏은 이제 기본 공개 경로만이 아니라 profile 덮어쓰기와
운영 코드 filter chain의 `permitAll`·`securityMatcher` 문장까지 고정한다
(`docs/security/public-paths-snapshot.txt`). 그런데 그 검사를 설명하는 세
곳은 아직 「기본 공개 경로」만 본다고 적는다.

- gates.md 2절 `verifyPublicPathSnapshot` 행
- 루트 build.gradle `verifyPublicPathSnapshot` 태스크 description
- app-bootstrap build.gradle `publicPathSnapshotTest` 레인 description

세 곳 모두 지금 범위(기본값, profile 덮어쓰기, filter chain 문장)로 고친다.
동작 변경 없음.

검증: scripts/verify.sh docs(노트북) rc=0. 이 문구를 고정하는 시험은 없다
(git grep 'shipped public path default' -- '*.java': 0건).

Refs: round9 확인 리뷰(r9-be가 넘긴 Low, 공개 경로 범위 확장 뒤)
2026-11-13 08:32:49 +09:00

27 KiB

게이트

무엇을, 언제, 어디서 돌리는지 정한다. 무엇이 한 단계인지는 build.gradle의 단계 태스크(prCheck·mainCheck·integrationCheck·performanceCheck·releaseCheck)가 정한다. workflow(.gitea/workflows/의 pr.yml·main.yml·release.yml)와 scripts/verify.sh는 그 태스크를 부르기만 한다. 이 문서와 그 셋이 다르면 그 셋이 맞고, 이 문서를 고친다. 실행 위치(desktop, 잠금)는 operate.md 「실행 위치」다.

작업 중      scripts/verify.sh leaf <gradle-path>  (+ 그 leaf의 관련 strict lane)
묶음 끝      + architectureCheck · 바뀐 표면의 검사(env 키·공개 경로·의존성 잠금) · 관련 lane
라운드 끝    합친 트리에서 scripts/verify.sh round — workflow가 PR·main·nightly·태그에서 돌리는 것과 같은 명령

1. 게이트 목록

Gradle 명령과 scripts/verify.sh는 모두 저장소 루트(Gradle 루트)에서 실행한다. verify.sh는 Gradle·Docker가 드는 단계를 desktop으로 옮겨 잠금 아래에서 돌린다(operate.md 4.1절). leaf의 Gradle path는 gradle/modules.json의 gradle_path에서 읽는다. leaf별 명령 목록을 문서에 적지 않는다.

scripts/verify.sh 단계 무엇을 돌리나 workflow
docs check-work-docs.py, check-docs.py, scripts/tests 자기 시험, check-repo-layout.py(Gradle 없음, 노트북 가능) pr.yml의 prCheck 안
leaf <gradle-path> 그 leaf의 check —
pr ./gradlew :prCheck, ./gradlew :verifyStrictLaneStages --dry-run pr.yml done
main :integrationCheck :mainCheck --continue, -p build-logic test, scripts/ci/verify-configuration-cache.sh main.yml(push)
nightly compose smoke 전부, 마지막에 :performanceCheck --continue main.yml(schedule·수동)
release :releaseCheck(지금 커밋을 provenance로) release.yml release
app scripts/bootstrap-local.sh(앱을 띄워 health와 기본 endpoint 확인) —
round pr → main → nightly → release, 첫 실패에서 멈춘다 —

workflow에만 있는 job: pr.yml done의 마지막 step과 main.yml의 vulnerabilities(trivy, scripts/ci/trivy-scan.sh), main.yml의 links(lychee), nightly job(jpa-postgresql·httpclient-transport·redis-topology·fileserver-nfs-ambiguity·notification-chaos·jpa-next), release.yml의 release lane과 이미지 job. main.yml의 done은 게이트가 아니다: nightly에 main에서 :prCheck를 한 번 더 돌려 빌드 캐시를 채우고, 같은 이름의 PR job이 그 캐시를 읽는다(setup-gradle이 job 이름으로 캐시를 찾는다). 도구를 내려받거나 runner 환경이 필요해 verify.sh에 넣지 않았다. 손으로 돌리는 법은 3절 (다)다.

게이트 하나씩:

게이트 무엇 단계 정의·workflow
./gradlew <gradle-path>:check 그 leaf만: 컴파일, 테스트, Spotless, Checkstyle, Error Prone, API surface 작업 중 leaf 컨벤션 플러그인
architectureCheck 의존 방향, domain-core·shared-contract·application-* 순수성, Git이 옮길 수 있는 소스, ArchUnit PR(ci 안) build.gradle
./gradlew :app-bootstrap:architectureTest 저장소 전체 ArchUnit suite만 작업 중 app-bootstrap architectureTest source set
qualityCheck SpotBugs, FindSecBugs(운영 코드) PR(ci 안) build.gradle
testQualityCheck 같은 분석을 모든 테스트 source set에(config/spotbugs/exclude-test.xml 기준) main(mainCheck 안) build.gradle
ci leaf check(API surface 포함) + architectureCheck + qualityCheck PR(prCheck 안) build.gradle
prCheck ci + verifyDependencyLocks + verifyComposeProfiles(compose lane이 선언대로 렌더링되는가) + verifyRepositoryLayout(check-repo-layout.py) + verifyWorkDocs(check-work-docs.py) + documentCheck(check-docs.py, 앞에 scripts/tests 자기 시험) PR pr.yml done: ./gradlew :prCheck
verifyStrictLaneStages --dry-run explicitOnly가 아닌 strict lane이 단계 태스크 하나의 계획에 들어 있는가(그래프 검사), 단계마다 선언한 workflow job이 ./gradlew <단계> 한 줄을 정해진 조건으로 돌리는가(형식 검사) PR pr.yml done 둘째 줄. 형식은 build-logic/AGENTS.md
python3 scripts/check-repo-layout.py 저장소 루트와 src/ 최상위에 허용 목록 밖의 항목이 없는가, registry 경로가 허용 폴더 안인가. 아무도 가리키지 않는 compose·스크립트 파일은 경고 PR(prCheck 안) verifyRepositoryLayout
python3 scripts/check-work-docs.py 작업 지침(루트 AGENTS.md·CLAUDE.md, docs/work/, src/**/AGENTS.md, .claude/)의 분량 상한, 본문 이력 ID 0, playbook 뼈대, 상대 링크 PR(prCheck 안) verifyWorkDocs
python3 scripts/check-docs.py 살아 있는 문서의 언어, 기록·ADR 머리 블록, 문서의 인라인 코드 경로·Gradle 경로가 지금 있는가, 복사한 숫자, 상대 링크(docs/README.md 「문서 검사」) PR(prCheck 안) documentCheck
mainCheck configContractCheck + qualificationCheck(testQualityCheck 포함) + 공개 경로 스냅숏 + 전송·메시징 qualification lane + GraphQL 전송 경계 lane(graphqlStableTest) + 생성 명령 왕복(verifyFeatureScaffold) + 모든 leaf의 mainCheck(document-contract lane 등) main main.yml main: ./gradlew :integrationCheck :mainCheck --continue
integrationCheck 선언된 strict integration lane 전체(실 컨테이너). 입력이 없는 lane은 빼고 이름을 댄다 main·nightly main.yml main: ./gradlew :integrationCheck :mainCheck --continue(두 단계를 Gradle 한 번에. 한 번 컴파일하고, 직렬 lane이 도는 동안 나머지가 겹친다. integration이 앞이라 lane이 첫 몇 분부터 슬롯을 쓴다)
performanceCheck 선언된 performance lane 전체(부하·종료·풀·자원 한계, 실 서버와 컨테이너). 상한을 매번 단언한다. 손으로 돌리든 workflow든 같은 상한이다 nightly(다른 무거운 job 뒤: 파일 맨 끝 job이고 runner 하나가 job을 만든 순서대로 돈다. needs는 쓰지 않는다 — Gitea 1.27이 needs와 if를 함께 가진 job을 Blocked에 둔다) main.yml performance. 5절
releaseCheck 릴리스 provenance + 공개 경로 스냅숏. 커밋을 GITHUB_SHA·GIT_SHA·-PgitRevision=<sha>로 받고, 없으면 설계대로 실패한다 태그 release.yml release
:app-bootstrap:verifyEnvKeys env 키 레지스트리와 profile YAML·.env.example mainCheck 안(configContractCheck) build-logic ca.config-contract
verifyPublicPathSnapshot 공개 경로 표면(기본값, profile 덮어쓰기, 운영 코드 filter chain의 permitAll·securityMatcher 문장)이 docs/security/public-paths-snapshot.txt와 같은가 mainCheck·releaseCheck 안 build.gradle
verifyDependencyLocks lockfile PR(prCheck 안) build.gradle
:app-bootstrap:documentContractTest 문서와 코드를 대조하는 lane(태그 document-contract) main(mainCheck 안) src/bootstrap/app/build.gradle
:app-bootstrap:repositoryContractTest 빌드 스크립트·workflow·compose를 읽는 계약(태그 repository-contract) PR src/bootstrap/app/build.gradle
  • leaf의 check는 그 leaf만 본다. 저장소 전체 질문은 이름이 따로 있는 루트 태스크가 답한다.
  • 전체 test·check·ci는 brief가 시킬 때 돌린다.
  • 공개 경로 검사와 env 키 검사는 그 표면이 바뀌었을 때 돌린다.

2. 바꾼 것에 맞춰 고르기

바꾼 것 추가로 돌릴 것
한 leaf 안의 코드 그 leaf check + 그 코드를 지키는 strict lane(실 DB 등)
leaf 경계·의존·registry architectureCheck, verifyDependencyLocks
env 키 :app-bootstrap:verifyEnvKeys
공개 경로·보안 체인 verifyPublicPathSnapshot
의존성 verifyDependencyLocks
문서(docs/**, AGENTS.md·CLAUDE.md, README) 그 문서를 읽는 document-contract lane(예: :app-bootstrap:documentContractTest) + 링크 검사(아래) + python3 scripts/check-docs.py
파일·폴더·Gradle 프로젝트를 지우거나 옮김 python3 scripts/check-docs.py(문서가 가리키던 경로가 사라진다)
docs/work/, 루트 AGENTS.md·CLAUDE.md, src/**/AGENTS.md, .claude/ 아래 문서 python3 scripts/check-work-docs.py
다른 매뉴얼에서 이력 ID를 걷어냄 python3 scripts/check-work-docs.py --history <파일 또는 폴더>
build-logic·workflow(.gitea/) -p build-logic check javadoc, verifyStrictLaneStages --dry-run
패키지 규칙, 생성 명령 템플릿 verifyFeatureScaffold(mainCheck 안)
마이그레이션 persistence-jpa check, 잠금 대기 lane(postgresqlMigrationLockWaitIntegrationTest), 마이그레이션 lane
테스트 코드(ArchUnit fixture 포함) 그 leaf testQualityCheck
compose·Dockerfile verifyComposeProfiles(compose 렌더링), 실제 docker build와 기동(scripts/verify.sh nightly의 smoke)
  • ArchUnit 위반·허용 fixture도 testQualityCheck(SpotBugs)가 분석한다. 외부 라이브러리의 Lombok 클래스를 상속한 fixture는 SpotBugs가 lombok.Generated를 찾지 못해 실패한다(missing analysis class). 그런 상속 fixture는 두지 않는다.

어떤 테스트가 그 문서를 읽는지는 grep -rn -e '<파일 이름>' -e '<폴더 경로>' src --include=*.java로 찾는다. 걸리는 테스트가 없으면(주석만 걸려도 없음이다) document-contract lane은 돌리지 않고 grep 명령과 결과를 보고에 적는다. 리뷰 기록(docs/reviews/**)도 같다. brief가 돌릴 lane을 정했으면 그 lane을 돌린다(brief가 먼저다).

탐침: 의심 결함이나 RED를 보려고 별도 worktree에서 잠깐 돌리는 테스트다. 버릴 worktree에서만 돌리고 커밋하지 않는다.

  • 탐침마다 무엇을 단언했는지 적는다. 결함 동작을 단언했으면 rc=0이 확인이고, 약속(Javadoc·결정)을 단언했으면 실패가 확인이다. 둘이 섞이면 rc만으로 결과를 읽을 수 없다.
  • strict lane에 --tests를 붙여 탐침만 돌려도 된다. 단 requires(클래스 이름)로 고르는 lane은 고른 클래스가 모두 돌지 않으면 실패한다(StrictTestLanePlugin의 required 검사). 그 lane은 필터 없이 돌린다. 필터 실행은 탐침의 증거일 뿐 lane 통과의 증거가 아니다.
  • 커밋하는 수정이 그 source set에 없던 의존성을 쓰면 lockfile도 같은 커밋에 넣는다. desktop worktree에서 ./gradlew <gradle-path>:resolveAndLockAll --write-locks로 다시 만들어 가져오고 verifyDependencyLocks로 본다. 손으로 고친 lockfile은 Gradle이 실제로 고른 버전과 다를 수 있다.
  • 탐침이 그 source set에 없는 의존성을 써야 하면 버릴 worktree에서만 build.gradle 한 줄을 더하고 --write-locks로 돌린다. 바꾼 줄(빌드 파일, lockfile)을 실행 기록에 적는다. 그렇게 하지 않기로 했으면 코드 읽기 증거(E1)로 판정한다.

링크 검사: 상대 링크는 PR마다 scripts/check-docs.py의 link가 살아 있는 문서 전부(src/**/AGENTS.md, .claude/ 아래 문서 포함)를 본다. 외부 URL까지 보는 lychee는 문서 검사라 main 단계다(main.yml links, 범위 README.md, docs/build.md, src/**/README.md, src/**/AGENTS.md, docs/**/*.md, .github/**/*.md. 폴더 CLAUDE.md는 @AGENTS.md 한 줄이라 링크가 없다). 저장소 밖 경로와 file:line은 링크로 쓰지 않는다(lychee가 따라가지 못한다).

3. 라운드 끝 — 합친 트리의 전체 묶음

여러 묶음을 합친 트리는 workflow가 PR·main·nightly·태그에서 돌리는 단계를 모두 돌린다. 경로 필터로 켜지는 job은 없다(2026-11-08부터, 단계 workflow의 경로 필터는 verifyStrictLaneStages가 거절한다). (가)는 scripts/verify.sh 단계, (나)는 workflow에만 있는 job이다. 한 번에 하나씩, 공유 잠금 아래에서 돈다(verify.sh가 잠근다).

단계별 묶음. brief가 단계 이름으로 게이트를 시키면 같은 이름의 verify.sh 단계를 돈다.

brief의 말 돌릴 것
pull request 단계 게이트 scripts/verify.sh pr --no-cache + scripts/verify.sh docs
main 단계 scripts/verify.sh main --no-cache
nightly, compose smoke, 성능 scripts/verify.sh nightly --no-cache
라운드 끝 scripts/verify.sh round --no-cache + scripts/verify.sh docs, 그리고 (나)에서 바뀐 영역에 걸리는 job
  • release 단계(releaseCheck)는 합친 트리에서 provenance와 공개 경로 스냅숏이 깨지지 않았는지만 본다. release.yml의 다른 job(web·websocket·httpclient·jpa·fileserver release gate, 이미지)은 릴리스 전에만 돈다(operate.md 4.3절). 결과 표에 "태그 단계 — 라운드 끝 아님"으로 적는다.
  • verify.sh는 단계 하나를 로그 하나(~/<로그 이름>-logs/<단계>.log)로 남긴다. 4절 표에는 그 안의 Gradle 명령마다 한 줄을 쓴다.

실제로 돌았음을 보이기. --on desktop(기본)은 새 detached worktree에서 시작한다. --no-cache가 모든 Gradle 명령에 --no-build-cache를 붙인다. 바뀌는 것은 캐시 사용뿐이라 판정은 같다. 로그마다 grep -c 'FROM-CACHE' <로그>가 0이어야 한다. UP-TO-DATE는 같은 worktree에서 앞 명령이 만든 출력일 때만 받아들인다(4절). --rerun은 바로 앞 태스크 하나에만 걸려 ci 같은 집계 태스크의 증거가 되지 않는다.

  • mainCheck 안의 verifyFeatureScaffold는 생성한 복사본에서 Gradle을 따로 띄워(scripts/verify-feature-scaffold.sh) 바깥의 --no-build-cache를 받지 않는다. 바깥 빌드는 FROM-CACHE를 만들 수 없으니 그 로그에 나온 FROM-CACHE는 중첩 빌드의 것이다. 「실제 실행」 칸에 "바깥 FROM-CACHE 0, 중첩 빌드 FROM-CACHE N(태스크 이름)"으로 적는다.
  • verify.sh를 쓸 수 없는 환경이면 단계 함수의 명령을 저장소 루트에서 그대로 차례로 돈다. 단계 함수가 명령의 정본이다.
  • 첫 실행이 실패하면 고치고 다시 돌린다. 둘 다 기록한다.
  • 합친 뒤에만 드러나는 결함이 있다. 묶음별 검증으로 이 단계를 대신하지 않는다.

(나) workflow에만 있는 job — brief의 "바뀐 영역의 lane"은 이것이다:

  1. 바뀐 파일 목록을 만든다: git diff --name-only <기준 커밋> <합친 커밋>.
  2. 바뀐 영역의 job을 고른다: PostgreSQL major(jpa-postgresql, persistence-jpa), HTTP transport(httpclient-transport, httpclient), Redis topology(redis-topology, redis leaf 셋), NFS(fileserver-nfs-ambiguity, fileserver), 알림 chaos(notification-chaos), 릴리스 lane(release.yml의 같은 영역 job).
  3. 그 job의 run 줄을 저장소 루트에서 그대로 돌린다. 행렬은 값마다 한 번이다. redis-topology는 행렬이 아니라 행마다 step 하나이고, 그 scripts/ci/redis-topology.sh <topology> <version> 줄은 desktop에서도 같은 줄로 돈다. desktop에서는 앞에 GRADLE_OPTS=-Dorg.gradle.daemon=false를 붙인다(스크립트 안의 ./gradlew가 daemon을 남기지 않게. CI는 step 사이에 daemon을 다시 쓴다).
  4. 고르지 않은 job은 이름과 "바뀐 영역 아님"을 결과 표에 적는다.
  5. 처음 켠 job이 이번 변경과 무관한 이전부터의 실패를 드러내면(예: 진입 문서만 바꿨는데 그 영역 job을 돌림), 기준 커밋에서 같은 실패인지 보고 「이전부터」로 적는다. 그 영역의 남은 문제로 넘기고 이번 변경 몫으로 세지 않는다.

(다) 로컬에 도구가 없는 것:

job 로컬에서 대체가 못 보는 것
main.yml links(lychee) scripts/verify.sh docs의 상대 링크 검사. desktop에 lychee 공식 이미지가 이미 있으면 그 이미지로 같은 범위를 돌린다 외부 URL
vulnerabilities(trivy) 이미 설치된 trivy나 desktop에 이미 있는 trivy 공식 이미지가 있으면 scripts/ci/trivy-scan.sh의 검사 줄 그대로. 그 버전이 없으면 있는 버전으로 기준 트리와 이번 트리를 같은 DB로 돌려 새로 생긴 걸림만 이번 변경 몫으로 본다. 스크립트가 trivy를 내려받아 설치하는 부분은 따라 하지 않는다(operate.md 4.1절). 없으면 못 돌림 전부(못 돌렸을 때)

4. 결과 기록

단계 게이트(명령) 결과 시간 실행 직전 1분 부하 실제 실행 로그
PR :prCheck --no-build-cache rc=0 6분 32초 0.39 태스크 756 executed, FROM-CACHE 0, 테스트 7298 실패 0 desktop ~/<작업 이름>-logs/pr.log
  • 한 줄은 명령 하나다. verify.sh 단계 하나는 Gradle 명령 여럿이다. 명령마다 한 줄을 쓰고 「게이트」 칸에 main 2/4처럼 순번을 붙인다. Gradle의 태스크 집계 줄(BUILD SUCCESSFUL in …, N actionable tasks)은 명령마다 하나씩 나오므로 단계 로그에서 명령별로 나눠 읽는다.
  • 「실제 실행」 칸은 로그의 > Task 줄에서 센다: executed(꼬리 없음), UP-TO-DATE, FROM-CACHE. 테스트 수는 그 명령이 새로 쓴 JUnit XML에서 센다.

테스트 수 세기. 성공한 Gradle 로그(--console=plain)에는 테스트 수가 찍히지 않는다. 같은 worktree의 다음 실행(특히 --tests 필터 실행)은 같은 leaf의 XML을 덮어쓴다. 그래서 명령이 끝날 때마다 XML을 로그 폴더로 복사하고 사본에서 센다.

cp -r <leaf 경로>/build/test-results/<태스크> ~/<작업 이름>-logs/<명령 이름>-xml
x=~/<작업 이름>-logs/<명령 이름>-xml
for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') | grep -o '<testsuite [^>]*' | grep -o " $k=\"[0-9]*\"" | tr -dc '0-9\n' | awk -v k=$k '{s+=$1} END {print k"="s+0}'; done

앞 실행을 증거로 쓰기. 다시 돌리지 않고 앞 실행을 증거로 쓸 수 있는 것은 둘이다.

  • 같은 worktree에서 앞 명령이 만든 출력이라 이번 명령의 태스크가 UP-TO-DATE로 끝났다. 앞 명령의 로그와 XML 사본을 함께 적는다.
  • 같은 트리 해시에서 돈 자기 실행 로그가 있다(맡은 발견이 이미 커밋된 수정에 들어 있을 때 등). 로그에 적힌 트리 해시와 지금 트리 해시를 함께 적는다.
  • 트리가 다르거나 다른 세션 보고의 「통과」는 증거가 아니다(E0). 다시 돌린다.

smoke 이미지가 이 트리에서 만들어졌음을 보이기. smoke·compose lane은 Docker 레이어 캐시를 쓴다. 이미지 생성 시각은 runtime 레이어가 캐시에서 오면 증거가 못 된다. 앱 jar를 복사하는 단계가 smoke 로그의 build 출력에서 CACHED가 아닌지 본다. 앱 jar가 이 트리에서 새로 만들어졌으면 그 단계는 캐시가 될 수 없다. 결과 표 「실제 실행」 칸에 그 줄과 이미지 id를 적는다.

원래 있던 실패 가리기. 시간·자원에 기대는 실패(OOM, 시간 초과, 순서 의존)는 기준 커밋과 이번 트리에서 같은 명령을 각각 세 번 돌린다. 기준에서 한 번이라도 같은 원인(같은 테스트, 로그의 같은 OOM·시간 초과)으로 실패하면 이전부터의 실패로 적는다. 기준에서 세 번 다 통과하고 이번 트리에서만 실패하면 이번 변경 몫이다. 순서 의존을 재현하려면 그 테스트 클래스를 --tests <클래스> --rerun으로 열 번 돌리고, 부하가 필요하면 잠금을 쥔 채 nproc개의 yes > /dev/null &를 띄웠다가 끝나면 끈다. 실패한 반복 수를 적는다.

공유 잠금 기다리기. 순서는 flock이 정한다(먼저 잡은 쪽). 따로 순번을 정하지 않는다. 기다리는 명령은 background로 두고 다른 일을 하며, 대기는 완료나 첫 실패에서 끝나는 것 하나로 둔다. 30분 넘게 못 잡으면 ps -o pid,etime,args -C flock으로 쥔 쪽을 보고 맡긴 쪽에 알린다(operate.md 7절).

함께 적는다:

  • 대상 커밋 sha. 작업 트리가 커밋되지 않았으면 그렇다고 적는다.
  • 못 돌린 것과 이유. 이유 없이 빠진 검증은 HARD-STOP 6 위반이다.
  • 캐시로 통과한 것. 실행 시간이 짧으면 캐시 재사용인지 적는다.
  • 집계가 뺀 lane. 입력이 없어 빠진 lane의 이름.
  • 고친 테스트가 실제로 돌았는지. 큰 집계 안에서 몇 개가 돌았는지 테스트 수로.
  • 보고한 태스크가 로그에 있는지. 로그에서 태스크 이름을 grep해 확인한다.

5. 성능 lane

  • performance lane은 상한을 매번 단언한다. 측정만 하고 통과하는 모드는 없다. 정본은 build-logic/AGENTS.md 「lane 캐시와 성능 lane」과 docs/testing/TESTING_STRATEGY.md의 PERFORMANCE 문단이다.
  • strict lane convention이 테스트 JVM에 performance.assertions.enabled=true를 넣는다. leaf나 lane은 이 값을 선언하지 않는다.
  • 빌드(-P, GRADLE_OPTS)나 lane이 true 아닌 값을 주면 테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다. -Pperformance.assertions.enabled=true는 받지만 줄 필요가 없다.
  • 그래서 desktop에서 손으로 돌리는 ./gradlew performanceCheck와 workflow가 같은 상한을 단언한다.
  • 판정 없이 숫자만 보려면 JMH가 있는 leaf의 ./gradlew :<leaf>:jmh를 쓴다. 게이트가 아니다.
  • 시간 단언은 다른 빌드가 돌지 않는 머신에서만 뜻이 있다. 그래서 performance lane은 PR·main 단계가 아니라 performanceCheck에 있다.

회귀를 막는 장치:

장치 고정하는 것 단계
자원 한계 lane Tomcat·Jetty 부하·느린 클라이언트·종료, HTTP client 풀·스트리밍·재시도, Hikari 풀 performanceCheck
JMH 벤치마크 src/adapter/outbound/httpclient/src/jmh(메시징 벤치마크는 messaging-library repo로 옮겼다) 명시 실행

6. 게이트를 믿을 조건 — 거짓 통과 막기

초록이라는 사실만으로 그 게이트가 무언가를 막았다는 뜻은 아니다.

거짓 통과 모양 지금의 장치
어떤 단계도 돌리지 않는 lane verifyStrictLaneStages --dry-run(PR)의 그래프 검사
단계 job이 단계를 조용히 돌리지 않음(바뀐 명령 줄, if:, continue-on-error, 경로 필터) verifyStrictLaneStages --dry-run의 형식 검사(build-logic/AGENTS.md 「단계 job의 모양」)
lane 정책을 바꿨는데 캐시가 옛 결과로 통과 lane 정책 값을 Test 입력으로
게이트 밖에서 실패한 채 방치된 검사 testQualityCheck(mainCheck)
실서버 계약이 어느 게이트에도 없음 lane을 단계에 연결
시간 단언을 끈 채 performance lane 실행 convention이 단언을 켜고, 끄는 값이나 skip이 있으면 테스트 전에 실패(5절)
캐시에서 가져온 결과를 지금 통과한 것으로 셈 기준 상태 확인과 시간·환경에 민감한 테스트는 그 태스크를 --rerun으로 다시 돌린다. --rerun은 바로 앞 태스크 하나에만 걸리므로 태스크마다 붙인다. 집계 태스크는 새 worktree와 --no-build-cache로 돌리고 FROM-CACHE 0을 보인다(3절)
외부 이미지가 사라져 다른 lane 결과까지 가림 테스트 이미지를 gradle/container-images.properties 한 곳에 digest로 고정, main 단계는 --continue
smoke rc=0인데 앱이 OOM으로 재시작함 scripts/run-compose-runtime-smoke.sh가 lane 컨테이너 재시작·OOMKilled를 실패로 보고 restarts.txt·app-memory-peak-bytes.txt를 남긴다. 그 밖의 compose 실행은 docker inspect -f '{{.RestartCount}} {{.State.OOMKilled}}' <컨테이너>로 본다
셸 함수·if 조건 안에서 set -e가 꺼져 중간 실패가 지나감 실패를 받아야 하는 명령은 if·&&·`

게이트 장치 자체를 바꿨으면 일부러 망가뜨린 입력으로 실패하는 것을 본다. workflow를 바꿨으면 바꾸기 전후로 이벤트마다 계획되는 태스크 집합(--dry-run)을 비교한다.

7. workflow·검사 스크립트를 더할 때

리뷰는 빠진 검사만 찾기 쉽다. 장치를 더하기 전에 아래를 보고, 더하는 PR 본문에 답을 적는다. workflow 파일을 고치는 일은 CI 담당 작업이 한다.

  1. 어느 단계인가(PR·main·nightly·release). workflow 파일은 셋(pr.yml·main.yml·release.yml)뿐이다. 먼저 단계 태스크(prCheck 등)의 의존으로 넣을 수 있는지 보고, 안 되면 그 단계 파일의 job으로 넣는다. 새 workflow 파일과 모듈 이름의 workflow는 만들지 않는다.
  2. 새 job이 다른 단계가 이미 돌리는 태스크를 다시 돌리지 않는지 --dry-run 태스크 목록으로 보인다.
  3. lane 고르기·순서·집계는 Gradle에 둔다. 단계 job의 run:은 한 줄이다.
  4. 경로 필터를 새로 쓰려면 그 lane이 다른 단계에서 무조건 돈다는 것을 보인다.
  5. 문서·이름·개수·CI 배선을 검사하는 것은 main 단계다(2026-09-16 소유자 결정). PR에 두어야 하면 이유를 적는다.
  6. 이벤트별 job 수 변화와 잰 실행 시간을 적는다. runner 용량은 operate.md 4.1절의 값으로 판단한다.
  7. 실행 환경(Gitea)에서 돌지 않는 action·권한(id-token, ghcr, GitHub 의존성 그래프, upload-artifact@v4 이상)을 쓰지 않는다. 써야 하면 github.server_url 조건을 단다.
  8. Gradle 밖 검사 스크립트는 scripts/(workflow만 부르면 scripts/ci/)에 두고, 머리 주석에 누가 부르는지(workflow·Gradle·사람·훅)를 적는다. 부르는 곳이 없는 검사 스크립트는 만들지 않는다. 같은 일을 하는 빌드 태스크가 있으면 거기에 넣는다. 스크립트의 시험은 scripts/tests/에 unittest로 둔다. prCheck의 testDocumentChecks가 PR마다 python3 -m unittest discover -s scripts/tests로 돌린다.
  9. 같은 장치에서 결함이 두 라운드 연속 나오면 고치기 전에 그 장치가 필요한지 다시 본다(improve.md 7절).