Files
grpc-library/docs/work/release.md
T
DongHyeonka ce83f4d550
pr / ci (pull_request) Successful in 1m9s
docs: 별도 repo 라이브러리로서의 지침·작업 문서·릴리스 절차를 쓴다
옮겨 온 문서는 템플릿 안의 optional build를 전제로 했다(`-p
platforms/optional-build`, 템플릿 registry·workflow 경로, "벤더드 플랫폼").
하네스 뼈대의 루트 지침과 문제 정의는 비어 있었다.

- 루트 AGENTS.md(38줄)·CLAUDE.md: 꼭 지킬 것(core-api 순수성, Stable이
  advanced를 안 씀, 템플릿에 기대지 않음, 배포한 버전 불변, 버전 규칙),
  지도, 맡은 일, 검증 진입점. 비대화형 세션의 플러그인 설치 두 줄.
- README: 무엇인가, 받는 법(exclusiveContent), 지원 표, 구조, 문서 지도,
  서명, 이력(filter-repo, 커밋 SHA·리뷰 ID는 템플릿 기준).
- docs/work/README.md·gates.md·release.md: 고치는 법, 단계와 바꾼 것별
  게이트, 템플릿과 같이 고치기(composite), 릴리스와 소유자가 할 일
  (PACKAGES_TOKEN, SIGNING_KEY·SIGNING_PASSWORD, 첫 태그 v1.0.0).
- CHANGELOG.md(1.0.0 미발행, 옮기는 법), docs/README.md(지도, 머리 블록).
- scripts/verify.sh: unit·pr·main·release 단계. 라이브러리라 app은 없다.
- 살아 있는 문서(grpc·grpc-advanced AGENTS.md, 지원 매트릭스, runbook):
  경로·패키지·optional build 문장을 이 repo 기준으로. ADR·설계서 본문은
  기록이라 고치지 않았다.
- docs/vision.md는 소유자가 쓰는 문서라 비워 두었다.

검증: scripts/verify.sh docs rc=0(AGENTS.md 38줄, 장부 JSON).
2026-11-08 11:22:12 +09:00

5.4 KiB

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

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

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

1. 처음 한 번 — 소유자가 할 일

에이전트는 토큰·키를 만들거나 secret에 넣지 않는다. 아래는 소유자가 한다.

  1. 배포 토큰 PACKAGES_TOKEN: Gitea 웹 → 설정 → 애플리케이션 → 새 토큰. 권한은 package 읽기·쓰기만 준다(repository·user 권한은 주지 않는다). Gitea job 토큰(GITEA_TOKEN)은 패키지를 올릴 수 없어서 사람 토큰이 필요하다.

  2. 서명 키 SIGNING_KEY·SIGNING_PASSWORD: PGP 키 쌍 하나를 두 라이브러리(grpc, messaging)가 함께 쓴다.

    gpg --quick-generate-key "hyeonworks release <admin@hyeonworks.com>" ed25519 sign 2y
    
    gpg --armor --export-secret-keys <키 ID> > signing-key.asc
    

    signing-key.asc 내용 전체가 SIGNING_KEY, 키를 만들 때 넣은 암호가 SIGNING_PASSWORD다. 넣은 뒤 signing-key.asc는 지운다. 공개 키(gpg --armor --export <키 ID>)는 README 「서명」 절에 붙인다.

  3. repo secret 셋: grpc-library → 설정 → Actions → Secrets에 PACKAGES_TOKEN, SIGNING_KEY, SIGNING_PASSWORD.

  4. 첫 태그 v1.0.0: 아래 3절을 따른다.

2. 버전 규칙

  • SemVer, repo 하나에 버전 하나. 모든 모듈이 같은 버전으로 나간다. 태그는 vMAJOR.MINOR.PATCH이고 접미사(-rc.1 등)는 없다. 다른 모양의 태그는 ca.java-conventions가 빌드 전에 거부한다.
  • 공개 타입·proto의 삭제·시그니처 변경, 설정 키(app.grpc.platform.*) 바꾸기는 MAJOR다. 커밋 제목에 !, 본문에 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절).

  4. 태그를 단다.

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

  6. 템플릿이 이 라이브러리를 쓰게 되면(지금은 쓰지 않는다) 템플릿 PR로 카탈로그 버전을 올린다. 절차는 템플릿 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에 병합하고 같은 태그 이름을 새 커밋에 다시 달지 않는다. 다음 PATCH 태그를 쓴다
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로 넣는다.