Files
clean-architecture-backend-…/docs/ci-cd/template-vs-consumer.md
T
DongHyeonka ba3c964a92 ci(main): Redis 구성 lane 11행을 job 하나의 step으로 돈다
문제: nightly의 redis-topology가 행렬 job 11개였다. 행마다 job을 새로 시작해
컨테이너·checkout·JDK·Gradle 시작과 구성을 다시 치렀다. 수동 실행 run 100에서
이 11개가 runner 135분 가운데 26분이었고, 그중 약 3분의 1이 시작 비용이었다.

고른 방법: job 하나에 행마다 step 하나를 둔다. 각 step은 지금과 같은
`bash scripts/ci/redis-topology.sh <topology> <version>` 한 줄이다.
- `if: always()`로 한 행이 실패해도 나머지가 돈다. job이 빨갛게 되고, 실패한
  step 이름이 행을 말한다.
- 스크립트가 끝날 때 자기 topology를 내리므로 행끼리 서버를 나누지 않는다.
- 같은 job 안에서 Gradle daemon과 구성 결과를 다시 쓴다.
- timeout은 행 11개를 합친 시간에 맞춰 90분으로 둔다.

문서: 행렬이라고 적던 곳(gates.md, template-vs-consumer.md, redis-sdk compose
README, 스크립트 머리 주석)을 step으로 고친다.

버린 대안: 버전마다 job 하나(3개). 시작 비용을 셋 더 치른다. 한 step에서
셸 반복문으로 돌기: 어느 행이 실패했는지 로그를 뒤져야 하고, 단계 job 규칙과
같은 이유로 셸 문법을 늘리지 않는다.

위험·한계: UI에서 행마다 따로 보이던 초록·빨강이 step 단위가 된다. job 하나가
시간 제한에 걸리면 남은 행이 함께 멈춘다.

검증: YAML을 읽어 step 13개(checkout, setup, 행 11)를 확인했다. runner nightly
측정은 PR 본문에 적는다.
2026-11-12 18:57:05 +09:00

3.7 KiB

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(두 단계를 한 줄로)·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 전용" 열이 생성기가 벗겨 내야 할 목록이다.