Files
messaging-library/docs/work/release.md
DongHyeonka dd194784c3
main / main-check (push) Successful in 8m35s
docs: 별도 repo 라이브러리로서의 지침·작업 문서·릴리스 절차를 쓴다
옮겨 온 문서는 템플릿 안의 family를 전제로 쓰였다. 루트 지침은
하네스 뼈대의 빈 양식이고, 모듈 지침·제품 문서는 템플릿 경로
(src/platforms/messaging, src/config/…, cd src)와 템플릿 소비자
(app-bootstrap, adapter:*, composition:*)를 이 repo 안의 것처럼 부른다.

- AGENTS.md(38줄)·CLAUDE.md: 꼭 지킬 것 일곱(api 모듈 순수성, 템플릿
  타입·경로 금지, 배포 버전·적용된 migration 불변, 인증 manifest 손으로
  고치지 않기 등), 지도, 맡은 일, 검증 진입점.
- README.md: 받는 법(exclusiveContent dev.cakit), migration 위치, 지원 표
  (Boot 4.0.9, kafka-clients 4.1.2, apache/kafka:4.1.0, PostgreSQL 16,
  Java 21), 구조, 문서 지도, 서명 공개 키(지문 …A1C936D7F791F8AB,
  grpc-library와 같은 키), 이력(템플릿 2959eff0에서 filter-repo).
- CHANGELOG.md: 1.0.0 절과 템플릿 안 코드에서 옮기는 법(패키지,
  Kafka 설정 키, Gradle 좌표, 바뀌지 않는 것).
- docs/README.md, docs/work/{README,gates,release}.md,
  docs/problem-statement.md: grpc-library와 같은 모양으로, 메시징의
  인증 증거 게이트·migration 규칙·템플릿과 같이 고치는 경로를 넣었다.
  docs/vision.md는 소유자가 쓸 자리라 비워 둔다.
- messaging/AGENTS.md, docs/messaging/*, starter README: registry 경로를
  이 repo 기준으로, 템플릿 쪽 경로·타입은 「백엔드 템플릿의」로 밝혔다.
  시험이 읽는 문장(지원 표의 broker·버전, 설정 참조의 YAML)은 바꾸지
  않았다.

검증: scripts/verify.sh docs rc=0(vision.md 자리 알림만). desktop
mainCheck는 이 커밋 직전 트리에서 rc=0이었다. 문서가 시험에 읽히는
부분은 다음 desktop 실행으로 다시 본다.

Refs: design-docs repo-structure/05-library-repos.md 14.2절
2026-11-08 16:16:38 +09:00

7.4 KiB

릴리스 — 태그에서 Gitea Packages까지

이 문서는 messaging-library 버전을 내는 절차다. 버전을 내는 사람(소유자)과 릴리스를 준비하는 에이전트가 읽는다.

main 병합 ──> 소유자가 태그 vX.Y.Z push ──> .gitea/workflows/release.yml (desktop-runner)
                                               └─ ./gradlew releaseCheck release
                                                    1. 태그 형식·버전 확인 (verifyReleaseVersion)
                                                    2. hermetic lane + integration lane + 브로커 인증 증거 게이트
                                                       (testLaneCheck, integrationCheck, verifyMessagingCertificationEvidence)
                                                    3. SBOM 만들기 (releaseSbom, Trivy CycloneDX)
                                                    4. 의존성 취약점 검사 (HIGH·CRITICAL, KEV) — 여기까지 실패하면 아무것도 안 올라간다
                                                    5. 모든 모듈 + SBOM 서명해서 올리기 (publish…ToGiteaRepository)
                                                    6. 익명으로 maven-metadata.xml을 읽어 새 버전 확인

1. 비밀 값 — 소유자가 둔다

에이전트는 토큰·키를 만들거나 secret에 넣지 않는다. 소유자가 2026-11-08에 repo secret 셋을 등록했다.

secret 무엇 바꿀 때
PACKAGE_TOKEN Gitea 개인 토큰. 권한은 package 읽기·쓰기만(repository·user 권한 없음). Gitea job 토큰(GITEA_TOKEN)은 패키지를 올릴 수 없어서 사람 토큰이 필요하다 Gitea 웹 → 설정 → 애플리케이션에서 새로 만들어 secret을 덮어쓰고 옛 토큰을 지운다
SIGNING_KEY 서명용 PGP 비밀 키(ASCII armor 전체). 두 라이브러리(grpc, messaging)가 같은 키를 쓴다 새 키 쌍을 만들고 README 「서명」의 공개 키와 지문을 같은 PR에서 바꾼다. 만료(2028-11-07) 전에 한다
SIGNING_PASSWORD 그 키를 만들 때 정한 암호 한 줄. 키 파일이나 그 base64가 아니다 키와 함께
  • 이름: 설계(design-docs repo-structure/05-library-repos.md 7절)는 PACKAGES_TOKEN이라고 적었지만, 등록된 이름 PACKAGE_TOKEN에 workflow와 빌드를 맞췄다. 소유자에게 다시 등록을 부탁하지 않는다.
  • 서명 키: RSA 4096, 지문 92646CEAFE816CF8B9C249F0A1C936D7F791F8AB, 2028-11-07 만료. 공개 키는 README 「서명」이다.
  • 첫 태그는 v1.0.0이다(3절).

SIGNING_KEY에 넣는 것은 키 지문이나 키 ID(16진수 40·16·8글자)가 아니라 비밀 키 파일 전체다. 파일 그대로(여러 줄)나 그 파일을 base64로 한 줄로 만든 값(base64 -w0 signing-key.asc) 둘 다 된다. 빌드가 base64를 풀어 쓴다(SigningKeys).

gpg --armor --export-secret-keys 92646CEAFE816CF8B9C249F0A1C936D7F791F8AB > signing-key.asc
  1. signing-key.asc를 열어 첫 줄 -----BEGIN PGP PRIVATE KEY BLOCK-----부터 끝 줄 -----END PGP PRIVATE KEY BLOCK-----까지 줄바꿈 그대로 복사한다. RSA 4096 키면 100줄 남짓이다.
  2. Gitea → 그 repo(grpc-library, messaging-library 둘 다) → 설정 → Actions → Secrets → SIGNING_KEY를 고쳐 붙여 넣는다.
  3. Actions → signing-check → Run workflow(main). 로그에 PROBLEM 줄이 없고 gpg import: ok, secret key fingerprint 92646CEA…F791F8AB, signing with SIGNING_PASSWORD: ok가 나오면 된다. 이 workflow는 값을 출력하지 않는다(scripts/release/check-signing-key.sh).
  4. signing-key.asc를 지운다(shred -u signing-key.asc).

2. 버전 규칙

  • SemVer, repo 하나에 버전 하나. 모든 모듈이 같은 버전으로 나간다. 태그는 vMAJOR.MINOR.PATCH이고 접미사(-rc.1 등)는 없다. 다른 모양의 태그는 ca.java-conventions가 빌드 전에 거부한다.
  • 공개 타입의 삭제·시그니처 변경, 설정 키(app.messaging.*) 바꾸기, 적용된 migration의 위치(db/migration/messaging)·내용 바꾸기는 MAJOR다. migration은 원래 고치지 않는다(새 버전 파일을 더한다). 커밋 제목에 !, 본문에 BREAKING CHANGE:, CHANGELOG.md 그 버전 절에 옮기는 법을 쓴다.
  • 기능 추가는 MINOR, 고치기는 PATCH다.
  • SNAPSHOT은 내지 않는다. Gitea는 같은 버전을 다시 받지 않는다. 개발 중 연결은 composite build로 한다(docs/work/README.md 3절).
  • 배포한 버전은 지우지 않는다. 잘못 나갔거나 일부만 올라갔으면 그 버전은 버리고 다음 PATCH를 낸다. Gitea는 owner의 삭제를 막지 않으므로 이것은 규칙으로 지킨다.

3. 버전 내기

  1. main이 초록인지 본다(main.yml 마지막 실행).

  2. CHANGELOG.md에 그 버전 절을 쓰고 PR로 병합한다.

  3. 올리기 전까지를 desktop에서 미리 돌려 본다(비밀 값 없이, 4절). 비밀 값을 넣거나 바꾼 뒤 첫 태그라면 signing-check workflow도 한 번 돌린다(1절).

  4. 태그를 단다.

    git tag -a v1.0.0 -m "messaging-library 1.0.0"
    
    git push origin v1.0.0
    
  5. release.yml 실행이 초록인지 Gitea Actions 화면에서 본다. 마지막 줄들에 모듈마다 published: dev.cakit.messaging:<모듈>:<버전>이 찍힌다.

  6. 템플릿 PR로 카탈로그 버전(messagingLibrary)을 올린다. 절차는 템플릿 docs/work/reference/related-repos.md다.

4. 올리기 직전까지 미리 돌리기

scripts/verify.sh release --on desktop

releaseRehearsal이 releaseCheck를 돌고, 모든 모듈과 SBOM을 build/staging-repository에 올린 뒤 파일마다 확인한다(jar·sources·javadoc·POM·module 파일, 체크섬 넷, POM·module의 모든 의존성에 버전이 있는지). SIGNING_KEY가 환경에 있으면 .asc도 확인한다. 버전은 RELEASE_VERSION이 없으면 0.0.0이다.

5. 실패했을 때

어디서 뜻 할 일
1~4단계, 서명 아무것도 올라가지 않았다 고쳐서 main에 병합한다. 그 버전의 파일이 Packages에 하나도 없으면(maven-metadata.xml에 없음) 태그를 지우고 고친 main 커밋에 같은 태그를 다시 단다. 하나라도 올라갔으면 다음 PATCH를 쓴다
서명 직전 verifySigningKey, 또는 Could not read PGP secret key 서명 비밀 값이 키로 읽히지 않는다 signing-check workflow의 PROBLEM 줄이 원인이다(지문을 넣음, 줄바꿈 잃음, BEGIN·END 줄 빠짐, base64 손상, 다른 키, 암호 칸에 키를 넣음, 틀린 암호). 1절대로 다시 넣는다
5단계 중간 일부 모듈만 올라갔을 수 있다 그 버전은 버린다(지우지 않는다). 원인을 고치고 다음 PATCH를 낸다. CHANGELOG.md에 버린 버전을 적는다
6단계 올라갔지만 익명으로 안 읽힌다 owner 공개 설정을 확인한다. 템플릿 이미지 빌드가 토큰 없이 읽는다는 전제(설계 8.3절 R1)가 깨진 것이다

6. 취약점 정책

  • Trivy(버전·SHA-256은 scripts/tool.sh)가 커밋된 lockfile을 본다. HIGH·CRITICAL은 막고, MEDIUM·LOW는 보고만 하고, CISA KEV 목록에 있으면 등급과 상관없이 막는다. KEV 목록을 못 받으면 막는다.
  • 예외는 .trivyignore.yaml 한 곳에만 둔다. 항목마다 이유(statement)와 90일 안의 만료(expired_at)를 적고 PR로 넣는다.