문제: pr.yml은 gradle·vulnerabilities·done 세 job이고 필수 검사는 `done`이다. `done`은 앞 두 job이 끝나야 runner 대기열에 들어가는데, Gitea는 대기열에 들어온 순서로 job을 집는다. 그래서 그사이에 줄 선 다른 run의 job이 먼저 돈다. 2026-11-08 PR #7의 run 61은 gradle이 22:55에 끝났는데 `done`은 release 수동 실행(13 job)과 main 수동 실행(30 job)이 다 끝난 01:47에야 돌았다. job마다 checkout과 준비도 다시 한다. 고른 방법: `done` job 하나가 `./gradlew :prCheck`, `verifyStrictLaneStages --dry-run`, Trivy 검사를 차례로 돈다. 필수 검사 이름 `pr / done (pull_request)`은 그대로라 저장소 보호 규칙은 바꾸지 않는다. strict lane 단계 선언의 PR job을 `done`으로 바꾼다. 단계 job의 step은 `./gradlew` 한 줄만 허용했는데, 저장소 스크립트 한 줄(`bash scripts/<이름>.sh <단어>...`)도 허용한다. 자기 step이라 종료 코드가 job을 실패시키고 단계 줄의 결과를 가릴 수 없다. 셸 문법을 붙인 스크립트와 저장소 밖 명령은 여전히 막는다(TestKit 시험 셋을 더했다). 버린 대안: trivy를 Gradle Exec 태스크로 감싸 `./gradlew` 줄로 만들기. desktop verify가 도구를 내려받아 설치하게 된다(docs/work/operate.md 4.1절이 막는다). 위험·한계: Trivy가 마지막 step이라 Gradle이 실패하면 그 PR의 취약점 결과는 Gradle을 고친 뒤에 보인다. main push와 nightly가 같은 트리를 다시 검사한다. 검증: build-logic 시험(desktop), runner에서 이 PR의 `pr / done`.
53 lines
3.7 KiB
Markdown
53 lines
3.7 KiB
Markdown
# Template maintainer와 Template consumer의 검증은 다르다
|
|
|
|
## 결론
|
|
|
|
이 저장소에는 성격이 다른 두 종류의 검증이 섞여 있다.
|
|
|
|
1. **스켈레톤을 만드는 사람**에게 필요한 검증 — optional 모듈 조합이 모두 빌드되는가, 레지스트리가
|
|
확장 가능한가.
|
|
2. **스켈레톤을 가져다 서비스를 만드는 사람**에게 필요한 검증 — 내 애플리케이션의 테스트,
|
|
아키텍처 방향, 보안, 릴리스.
|
|
|
|
파생 프로젝트가 1번을 그대로 물려받으면, 자기 서비스와 아무 상관 없는 게이트를 평생 유지하게 된다.
|
|
이 문서는 어느 쪽이 어느 쪽인지 적어 둔다.
|
|
|
|
## Template 전용 (파생 프로젝트는 삭제해도 된다)
|
|
|
|
| 대상 | 무엇을 지키는가 |
|
|
| --- | --- |
|
|
| `docs/design/**`, `docs/history/**` | 이 템플릿을 만든 과정의 설계서·계획서·납품 패키지·증거·학습 기록 |
|
|
| `main.yml`의 nightly 행렬 job(`jpa-postgresql`, `httpclient-transport`, `redis-topology`, `fileserver-nfs-ambiguity`, `notification-chaos`, `jpa-next`, `object-storage-aws`)과 `release.yml`의 영역별 release lane | 템플릿이 광고하는 지원 매트릭스의 근거. 서비스가 그 capability를 쓰면 남기고, 지운 capability의 job은 같이 지운다 |
|
|
|
|
## Consumer 필수 (파생 프로젝트가 유지해야 한다)
|
|
|
|
| 대상 | 무엇을 지키는가 |
|
|
| --- | --- |
|
|
| `architectureCheck` | Clean Architecture 의존 방향. 이 템플릿의 존재 이유 |
|
|
| 각 leaf의 `check` | 컴파일 · 단위 테스트 · 포맷 · 스타일 · Error Prone |
|
|
| `qualityCheck` | SpotBugs / FindSecBugs |
|
|
| `configContractCheck` | 환경변수 계약 |
|
|
| `verifyDependencyLocks` | 재현 가능한 의존성 해석 |
|
|
| `pr.yml`(`./gradlew :prCheck`, 필수 검사 `pr / done`) | PR 단계. 무엇을 돌리는지는 Gradle 태스크 `prCheck`가 정한다 |
|
|
| `main.yml`의 `main`·`integration`·`build-logic`·`configuration-cache` job | main 단계(`mainCheck`, `integrationCheck`) |
|
|
| `main.yml`의 `performance` job | nightly 성능 단계(`performanceCheck`) |
|
|
| `pr.yml` `done`의 Trivy step과 `main.yml`의 `vulnerabilities` job(`scripts/ci/trivy-scan.sh`) | Trivy와 CISA KEV |
|
|
| `release.yml` | `releaseCheck`, 이미지 · SBOM · 서명 |
|
|
| `scripts/verify.sh` | 사람·세션이 workflow와 같은 단계를 돌리는 진입점 |
|
|
| `prCheck`의 `documentCheck`·`testDocumentChecks` | 문서 규칙(`scripts/check-docs.py`: 언어·머리 블록·참조·숫자·지도·링크·문체)과 Gradle 밖 스크립트·편집 훅의 시험(`scripts/tests/`). 파생 서비스의 문서도 같은 규칙을 따른다(`docs/README.md`) |
|
|
| `main.yml`의 `links` job | 문서의 외부 URL과 상대 링크(lychee) |
|
|
| `scripts/check-repo-layout.py`(`prCheck`의 `verifyRepositoryLayout`) | 저장소 최상위 배치. 서비스가 최상위 항목을 더하면 허용 목록과 `AGENTS.md` 지도를 함께 고친다 |
|
|
| action의 전체 URL·full SHA 핀 | 공급망 |
|
|
|
|
## 파생 프로젝트가 할 일
|
|
|
|
1. Template 전용 표의 항목을 삭제한다. 삭제는 대부분 파일 삭제 + `gradle/modules.json`
|
|
에서 leaf 항목 제거로 끝난다 — 레지스트리가 leaf 목록의 SSOT이고, 개수를 따로 적어 둔 곳은 없다.
|
|
2. `docs/ci-cd/boundary.md`의 경계를 그대로 유지한 채 자기 GitOps 저장소를 연결한다.
|
|
3. `.trivyignore.yaml`과 CODEOWNERS는 그대로 쓴다.
|
|
|
|
## 아직 하지 않은 것
|
|
|
|
Template CI와 Generated Application CI를 **물리적으로** 분리하지는 않았다(생성기 없음). 지금은 이
|
|
문서가 그 경계다. 생성기를 만든다면, 위 표의 "Template 전용" 열이 생성기가 벗겨 내야 할 목록이다.
|