Commit Graph
9 Commits
Author SHA1 Message Date
DongHyeonka a892a45073 fix(release): 서명 진단이 비밀번호 모양을 알리고 Gradle 서명기로도 서명해 본다
pr / ci (pull_request) Successful in 3m34s
signing-check(run 13)에서 base64를 푼 키는 맞았다. armor·CRC24·tag 5가
정상이고, 가져온 키 지문이 릴리스 키 92646CEA…F791F8AB였다. 남은 실패는
「SIGNING_PASSWORD로 서명이 안 된다」 하나인데, 비밀번호가 틀렸는지,
붙여 넣을 때 줄바꿈·공백이 섞였는지, gpg 쪽 문제인지 가를 수 없었다.
gpg는 비밀번호의 첫 줄만 읽고 Gradle은 값 전체를 쓰므로, gpg 판정이
Gradle 판정과 다를 수도 있었다.

- check-signing-key.sh: 비밀번호의 모양(글자 수, 줄바꿈·CR 수, 앞뒤 공백,
  비ASCII 수)과 서명 실패 때의 gpg 상태 키워드만 출력한다. 값은 출력하지
  않는다.
- verifySigningKey: 스크립트 뒤에 Gradle의 in-memory 서명기
  (signing.signatory)로 몇 바이트를 서명해 본다. Sign 태스크와 같은 판정이다.
  실패 문구는 BouncyCastle 예외 문장뿐이다. 둘 중 하나라도 실패하면
  태스크가 실패한다.

검증(로컬 gpg, 버리는 키): 맞는 비밀번호 ok, 틀린 비밀번호 「gpg status:
BEGIN_SIGNING FAILURE KEY_CONSIDERED」. 끝에 줄바꿈이 붙은 비밀번호는 gpg로
ok이고 모양 줄이 「line breaks 1」을 알린다(Gradle 판정은 desktop과 runner).
2026-11-08 15:21:16 +09:00
DongHyeonka 97f7381aae fix(release): base64로 감싼 armored 서명 키도 받는다
pr / ci (pull_request) Successful in 3m37s
진단을 다시 돌리자(signing-check run 11) SIGNING_KEY가 바뀌어 있었다.
4,632글자 한 줄, base64로 읽으면 3,474바이트이고 그 첫 바이트가
`-`였다. 곧 armored 키 파일을 base64로 한 줄에 감싼 값이다(CI secret에
여러 줄 값을 넣을 때 흔히 쓰는 방법). Gradle의 useInMemoryPgpKeys는
armored 글만 읽어서 이 값도 「Could not read PGP secret key」로 실패한다.

build-logic SigningKeys.armoured가 값을 받아, armored 블록을 base64로
감싼 것이면 풀어서 돌려준다. 그 밖의 값은 그대로 돌려줘 원래 오류로
실패하게 한다. 모듈 서명(LibraryPublishingPlugin)과 SBOM 서명(루트
build.gradle)이 이것을 거친다. check-signing-key.sh도 같은 규칙으로 풀어
본다. 「form: base64 of an armoured key file」을 알리고 풀린 글로 나머지를
검사한다. 키는 gpg에 환경 변수 대신 임시 폴더(0700, 끝나면 지움)의 파일로
넘긴다.

버린 대안: 소유자에게 여러 줄로 다시 넣게 하기. 지금 값도 키로는 맞을 수
있고, base64 한 줄은 secret 저장소가 여러 줄을 망가뜨릴 때의 표준 우회다.

검증(desktop, 버리는 RSA 4096 키):
- SigningKeysTest: 클래스가 없어 컴파일 실패(RED) → 통과(GREEN)
- check-signing-key.sh: armored·base64 둘 다 rc=0, base64 + 틀린 암호
  rc=1, 지문 rc=1
- base64 키로 서명 리허설: rc=0, 서명된 artifact 10개, gpg --verify Good
  signature
2026-11-08 15:14:28 +09:00
DongHyeonka 732cb26eb5 fix(release): SIGNING_KEY에 지문이 들어간 경우를 이름 대고 넣는 법을 적는다
pr / ci (pull_request) Successful in 3m42s
signing-check(run 10)로 v1.0.0 서명 실패의 원인을 찾았다. SIGNING_KEY
secret은 40글자 한 줄이었고 BEGIN·END 줄이 없었다. base64로 읽으면 30바이트,
첫 패킷 tag 55(0x37)였다. 16진수 40글자 지문 `92…`를 base64로 읽으면
첫 바이트가 0xF7, 곧 tag 0x37이다. 비밀 키 대신 키 지문이 들어갔다.

- check-signing-key.sh: 값이 16진수 8·16·40글자(키 ID·지문)면 그렇다고
  말한다. 릴리스 키 지문과 같으면 그것도 말한다(공개 정보만 비교한다).
- release.md 1절: SIGNING_KEY에 넣을 것(export 파일 전체, 줄바꿈 그대로),
  넣는 곳, signing-check로 확인하는 법. 3절: 비밀 값을 바꾼 뒤 첫 태그 전에
  signing-check. 5절: 서명 실패 행. 아무것도 게시되지 않았으면 태그를 고친
  커밋으로 옮겨 같은 버전을 쓴다는 규칙(총괄 결정과 같게).

검증: 지문 40글자를 넣은 경우 rc=1과 「key ID or fingerprint (the release
key's fingerprint)」. 앞 커밋의 시험 다섯은 그대로 통과한다.
2026-11-08 15:07:06 +09:00
DongHyeonka 5e0c89dab4 ci(release): 서명 비밀 값을 값 없이 진단하는 verifySigningKey를 더한다
v1.0.0 release(run 9)가 :grpc:grpc-contract:signMavenPublication에서
「Could not read PGP secret key」로 멈췄다. 원인 사슬은 BouncyCastle의
「secret key ring doesn't start with secret key tag: tag 0x37」이다.
Gradle은 키 문자열이 망가진 경우와 비밀번호가 틀린 경우를 같은 문장으로
알리고, secret은 로그에서 볼 수 없어 무엇이 틀렸는지 가릴 길이 없었다.

scripts/release/check-signing-key.sh가 값을 출력하지 않고 본다:
- 모양: 글자·줄 수, CR, 「\n」 문자열, 비ASCII, 앞뒤 공백
- armour: 첫 줄 BEGIN, 끝 줄 END, BEGIN 뒤 빈 줄
- base64 본문: 줄 너비, CRC24가 checksum 줄과 맞는지, 첫 패킷이 비밀
  키(tag 5)인지
- gpg가 가져오는지, 가져온 키의 지문(공개 정보)이 릴리스 키인지
- SIGNING_PASSWORD로 서명되는지(성공/실패만)

Gradle 태스크 verifySigningKey가 이 스크립트를 부른다. `release`는 이것에
의존하고(서명 키가 있으면 releaseRehearsal도), 모든 Sign 태스크는 그 뒤에
돈다. release.yml은 그대로 한 줄이다. 태그 없이 돌리는 수동 workflow
signing-check.yml을 더했다. 릴리스 키 지문은 gradle.properties
signingKeyFingerprint다.

검증(desktop, 버리는 RSA 4096 키): 정상 키 rc=0(모든 칸 yes, 서명 ok).
base64 줄 하나 뺀 키·한 줄로 붙인 키·틀린 비밀번호·다른 키는 각각 rc=1과
그 원인 줄. 같은 BouncyCastle 1.81로 망가뜨린 모양별 오류를 재현했다.
줄 누락은 tag 0x1·0xc·0xf처럼 임의의 tag를 낸다. 한 줄로 붙이거나 공백·
「\n」이 섞이면 0xffffffff, 비밀번호가 틀리면 checksum mismatch다.
2026-11-08 15:05:04 +09:00
DongHyeonka d9d1cfb55a ci(buf): 선언한 깨지는 schema 변경만 bufBreaking을 통과시킨다
bufBreaking은 기준(PR이면 merge base, main이면 직전 커밋)과 schema를
비교해 깨짐이면 무조건 실패했다. 그래서 일부러 깨는 변경(바로 앞 커밋의
proto 패키지 이름 바꾸기 같은 것)은 PR도 병합 뒤 main도 빨갛게 만들고,
통과시킬 길이 기준을 손으로 바꾸는 것뿐이었다.

기준과 HEAD 사이 커밋 하나가 `BREAKING CHANGE:` 꼬리말로 선언하면
통과시킨다. 커밋 규칙이 이미 깨지는 변경에 요구하는 표시이고, 그 표시가
MAJOR 버전의 근거다(docs/work/release.md 2절). 선언 없는 깨짐은 전처럼
실패하고, 고치는 길(되돌리기 또는 선언)을 말한다.

버린 대안: 첫 릴리스 전에는 검사를 끄기(태그 뒤의 첫 깨짐을 놓친다),
마지막 릴리스 태그와 비교(한 번 선언한 깨짐 뒤로 다음 릴리스까지 모든
PR이 빨개진다).

검증(desktop): HEAD c8f8721(BREAKING CHANGE 선언)과 기준 bbe49ac — 깨짐을
알리고 rc=0. 같은 트리에 꼬리말 없는 메시지로 바꾼 버리는 사본 — rc=1과
안내. gates.md 4절에 규칙을 적었다.
2026-11-08 14:08:07 +09:00
DongHyeonka ce83f4d550 docs: 별도 repo 라이브러리로서의 지침·작업 문서·릴리스 절차를 쓴다
pr / ci (pull_request) Successful in 1m9s
옮겨 온 문서는 템플릿 안의 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
DongHyeonka 239547bc2c fix(release): 리허설·릴리스 태스크가 프로젝트 좌표를 읽게 한다
releaseRehearsal과 release가 태스크 설정 블록 안에서 `path`·`group`·
`version`을 읽었다. 그 자리에서 셋은 프로젝트가 아니라 태스크의 속성이라
루트 publish 태스크 경로를 `:releaseRehearsal:publish…`로 만들고, 좌표를
`release:<모듈>:0.0.0`으로 찾았다. 좌표를 루트에서 한 번 잡아 쓴다.

같이 고친 것:
- grpc-core-api의 test fixtures 변형을 publication에서 뺀다. 이 repo
  시험끼리 쓰는 지원 코드이고(배포하는 testkit은 grpc-testkit), Maven이
  표현하지 못하는 capability라 POM 경고를 냈다.
- Trivy 호출에 --skip-version-check. 새 버전 알림이 매번 네트워크를
  부르고 로그를 덮었다.

검증(desktop): releaseRehearsal rc=0. 9개 모듈 + SBOM(733 components)이
staging에 올라가고 파일·체크섬 넷·POM/module 의존성 버전 확인 통과.
의존성 검사는 HIGH·CRITICAL 0, KEV 일치 0. 버리는 시험 키로 서명한
리허설도 rc=0, gpg --verify Good signature(키는 임시 폴더째 지웠다).
2026-11-08 11:20:11 +09:00
DongHyeonka 414666cfc7 build: 템플릿 밖에서 혼자 빌드·배포되는 Gradle 루트를 만든다
옮겨 온 gRPC 모듈은 템플릿의 두 번째 빌드(optional build)였다. 그 빌드는
템플릿 build-logic·카탈로그·registry·config를 상대 경로로 읽었고,
grpc-operation-ledger-jpa는 템플릿 persistence-jpa의 testFixtures 파일
셋을 빌드 때 복사해 왔다. 별도 repo에는 그 경로가 없다.

repo 루트를 Gradle 루트로 둔다.
- build-logic: 템플릿 22df3525의 src/build-logic을 복사하고 쓰지 않는
  플러그인(bootrun-dotenv, redis topology, config contract,
  spring-library, optional registry, purity 태스크)을 뺐다. 출처와 고친
  곳은 build-logic/UPSTREAM.md에 적었다(설계 10.3절 L1).
- registry config/architecture/modules.json: 템플릿의 optional-grpc 9행,
  source_path는 Gradle 루트 기준.
- 카탈로그·config: 이 repo가 쓰는 항목만. SpotBugs 제외는 이 repo
  클래스와 일반 규칙만 남겼다.
- group은 gradle.properties의 libraryGroup(com.hyeonworks.grpc)에서
  읽는다. 버전은 -PreleaseVersion 말고 RELEASE_TAG(vX.Y.Z)에서도 읽고,
  다른 모양의 태그는 빌드 전에 거부한다.
- 배포: 새 ca.library-publishing이 모듈마다 Maven publication(sources·
  javadoc jar, versionMapping으로 해석된 버전)과 저장소 gitea·staging,
  SIGNING_KEY가 있으면 PGP 서명을 단다. 루트는 SBOM artifact
  grpc-library와 단계 태스크 ci·mainCheck·releaseCheck·release·
  releaseRehearsal을 가진다. Trivy·Buf는 scripts/tool.sh가 SHA-256으로
  고정해 받는다.
- testFixtures 결합(설계 4.6절 2번)은 integrationTest 안 사본으로 끊었다.
- Buf lint·breaking은 Gradle 태스크(scripts/buf.sh)로 ci에 넣었다.

버린 대안: build-logic을 템플릿이 배포(L2, 순환), 공통 repo(L3, repo가
하나 더), 표준 플러그인만으로 새로 쓰기(L4, strict lane과 방향 검사를
잃음). SBOM은 CycloneDX Gradle 플러그인 대신 이미 고정해 쓰는 Trivy로
만든다(도구를 늘리지 않는다).

위험: strictlane 단계 검사는 included build 태스크를 따라가다 실패해서
그 태스크를 건너뛰게 고쳤다(UPSTREAM.md). Gitea에 실제로 올리는 경로는
비밀 값이 없어 이 커밋에서는 시험하지 못했다.

검증(desktop, 이 트리): ./gradlew ci rc=0, 테스트 739개(build-logic
포함) 중 첫 실행 실패 1개(템플릿 경로를 찾던 GrpcPackageOwnershipTest)를
고친 뒤 통과. ./gradlew verifyStrictLaneStages --dry-run rc=0.

Refs: design-docs repo-structure/05-library-repos.md 4.6·7·10절
2026-11-08 11:10:21 +09:00
DongHyeonka 76a9244d09 chore(harness): claude-harness 뼈대를 깐다
템플릿에서 옮긴 gRPC 이력 위에 새 repo의 작업 환경을 먼저 깐다.
claude-harness main 72078ca의 scripts/new-project.sh가 만든 파일을
그대로 복사했다: AGENTS.md·CLAUDE.md 양식, .claude/settings.json
(.env deny, 하네스 플러그인 harness@claude-harness 켜기),
scripts/verify.sh 뼈대, docs/vision.md·problem-statement.md·
adr/0000-template.md 양식, docs/ledger/ 빈 장부, .gitattributes,
.gitignore.

채울 자리(「(채울 것」)는 뒤 커밋에서 이 repo의 내용으로 채운다.
이 커밋 자체는 아직 빌드되지 않는다(Gradle 루트가 없다).

검증: new-project.sh 종료 코드 0, 남은 {{…}} 없음.

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