Files
clean-architecture-backend-…/docs/ci-cd/template-vs-consumer.md
T
DongHyeonka d46bab9659
pr / gradle (pull_request) Successful in 16m42s
pr / vulnerabilities (pull_request) Successful in 37s
pr / done (pull_request) Canceled after 0s
ci!: workflow를 pr·main·release 셋으로 접고 단계 job 모양만 검사한다
workflow 15개(+ composite action, jq 설치 스크립트)가 모듈 모양으로
나뉘어 있었고, 그것을 읽는 판독기(ShellScript·WorkflowGradleInvocations·
TaskSelectors, 운영 3,283줄과 그 시험 1,814줄)가 리뷰 라운드마다 새 셸
모양으로 결함을 냈다. 그런데 Gitea에서는 Actions가 꺼져 있어 workflow는
한 번도 돌지 않았다(design-docs repo-structure/03-ci.md 2.1·3.4절).

소유자가 정한 B안(같은 문서 7절, 11절 ①~⑧)대로 바꾼다.

- .gitea/workflows/pr.yml: `gradle` job이 `./gradlew :prCheck`와
  `./gradlew :verifyStrictLaneStages --dry-run` 두 줄, `vulnerabilities`
  (trivy), 필수 검사 하나 `done`.
- main.yml: push마다 mainCheck·integrationCheck·build-logic 시험·
  configuration cache·lychee·trivy·http3(권고). nightly·수동 실행에서
  PostgreSQL major·HTTP transport·Redis topology 행렬, NFS, 알림 chaos,
  jpa-next, compose smoke, 마지막에 `needs`로 performanceCheck.
- release.yml: releaseCheck와 기존 release lane, 이미지를 이 Gitea
  레지스트리에 올리고 cosign 키 쌍으로 서명한다. 수동 실행은 push·서명
  앞까지 돈다. upload/download-artifact를 쓰지 않는다. JPA 승격은
  `needs: jpa-release-gate`가 대신한다.
- 새 집계 `prCheck` = ci + verifyDependencyLocks + compose 렌더링 +
  저장소 배치 + 문서 검사(Exec). workflow와 verify.sh가 같은 한 줄을 쓴다.
- verifyStrictLaneStages: 그래프 검사(모든 strict lane이 선언한 단계의
  계획에 있다)는 그대로 두고, workflow 쪽은 고정 문자열 형식 검사로
  바꾼다. 단계마다 workflow·이벤트·필터·job·옵션·조건을 build.gradle에
  선언하고, 그 job의 step이 `run: ./gradlew <단계> <옵션>`을 가지며 다른
  run도 셸 문법 없는 ./gradlew 한 줄이고, 선언 밖의 if:, 조건 없는
  needs:, continue-on-error·shell:·defaults:, 따옴표 키·flow 형식, 다른
  working-directory, 선언 밖의 이벤트 필터가 없는지 본다. PR 단계 job
  하나는 이 검사 자신을 돌려야 한다. 셸 해석 코드와 그 시험을 지운다
  (build-logic 운영 코드 −3,167줄, 시험 −2,231줄). 우회 입력 21가지를
  TestKit 시험으로 둔다.
- scripts/verify.sh <단계>: 사람·세션의 진입점. 무거운 단계는 지금 작업
  트리를 패치로 desktop에 보내 잠금 아래에서 돌린다(operate.md 4.1절의
  손 절차). scripts/ci/는 workflow가 부르는 trivy·Redis topology·포트
  포워더·configuration cache 스크립트다.
- workflow를 읽는 시험(DeveloperExperienceContractTest, JpaRelease
  RenderingTest, FileserverDocumentationCoverageTest)과 입력 선언을
  .gitea로 옮기고, keyless 서명 시험을 키 쌍 서명 시험으로 바꾼다.
- 문서: gates.md·operate.md·docs/ci-cd·AGENTS.md(검증 절)·build-logic
  AGENTS.md(셸 규칙 문단을 세 줄로)·leaf 문서의 workflow 참조,
  docs/upgrade B-57~B-61.

버린 것: workflow 하나에 if:로 단계를 나누기(파일만 보고 단계를 알 수
없다), 레지스트리에서 생성(같은 정보의 셋째 사본), 바뀐 모듈만 돌리기
(결정 30과 충돌). 판독기를 남기고 고치기는 6라운드 13건이 반증했다.

위험: PR이 어댑터 컨테이너 lane과 Redis standalone lane을 더는 막지
않는다(main·nightly에서 빨갛게 된다. 소유자 결정 ②). main push는 ci를
다시 돌리지 않는다. 성능 lane은 매 push가 아니라 nightly에서만 돈다.
`.github/workflows/messaging-certification.yml`은 메시징 분리 작업이
지우므로 남겼다(.gitea가 있으면 Gitea가 읽지 않는다). 서명·push는 secret이
없어 실제 태그로는 돌려 보지 않았다.

BREAKING CHANGE: workflow 파일 위치와 이름, strictLaneStages 문법,
릴리스 레지스트리·서명 방식이 바뀌었다. docs/upgrade/2026-11-maturity-
review.md B-57~B-61을 따른다.
2026-11-08 21:55:43 +09:00

3.6 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·integration·build-logic·configuration-cache job main 단계(mainCheck, integrationCheck)
main.yml의 performance job nightly 성능 단계(performanceCheck)
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 전용 표의 항목을 삭제한다. 삭제는 대부분 파일 삭제 + config/architecture/modules.json 에서 leaf 항목 제거로 끝난다 — 레지스트리가 leaf 목록의 SSOT이고, 개수를 따로 적어 둔 곳은 없다.
  2. docs/ci-cd/boundary.md의 경계를 그대로 유지한 채 자기 GitOps 저장소를 연결한다.
  3. .trivyignore.yaml과 CODEOWNERS는 그대로 쓴다.

아직 하지 않은 것

Template CI와 Generated Application CI를 물리적으로 분리하지는 않았다(생성기 없음). 지금은 이 문서가 그 경계다. 생성기를 만든다면, 위 표의 "Template 전용" 열이 생성기가 벗겨 내야 할 목록이다.