# 릴리스 — 태그에서 Gitea Packages까지 이 문서는 grpc-library 버전을 내는 절차다. 버전을 내는 사람(소유자)과 릴리스를 준비하는 에이전트가 읽는다. ```text 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)가 함께 쓴다. ```bash gpg --quick-generate-key "hyeonworks release " ed25519 sign 2y ``` ```bash 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. 태그를 단다. ```bash git tag -a v1.0.0 -m "grpc-library 1.0.0" ``` ```bash git push origin v1.0.0 ``` 5. release.yml 실행이 초록인지 Gitea Actions 화면에서 본다. 마지막 줄들에 모듈마다 `published: com.hyeonworks.grpc:<모듈>:<버전>`이 찍힌다. 6. 템플릿이 이 라이브러리를 쓰게 되면(지금은 쓰지 않는다) 템플릿 PR로 카탈로그 버전을 올린다. 절차는 템플릿 `docs/work/reference/related-repos.md`다. ## 4. 올리기 직전까지 미리 돌리기 ```bash 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로 넣는다.