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
작업 방법 — grpc-library를 고칠 때
이 repo에서 일을 맡은 사람과 에이전트가 먼저 읽는다. 루트 AGENTS.md의 「꼭 지킬 것」이 이 문서보다 먼저다.
1. 일의 종류와 읽을 곳
| 일 | 먼저 읽을 곳 | 끝났다는 증거 |
|---|---|---|
| 모듈 코드 고치기·기능 더하기 | 그 family의 AGENTS.md(grpc/, grpc-advanced/), 관련 ADR(docs/adr/) |
바꾼 모듈 check + ci(2절) |
| proto 바꾸기 | grpc/grpc-contract/buf.yaml, ADR-GRPC-002 |
ci의 bufLint·bufBreaking. 깨지는 변경이면 MAJOR(release.md 2절) |
| 공개 타입·설정 키 바꾸기 | release.md 2절 |
CHANGELOG.md에 옮기는 법, 템플릿 쪽 영향 확인(3절) |
| 빌드 규칙(build-logic) 고치기 | build-logic/AGENTS.md, build-logic/UPSTREAM.md |
buildLogicTest(ci 안) |
| 릴리스 | release.md |
release.yml 초록, 익명 메타데이터에 새 버전 |
| 리뷰 | 아래 2절의 게이트 목록과 루트 AGENTS.md 「꼭 지킬 것」 |
발견마다 위치·재현·고칠 곳 |
2. 검증
- 진입점은
scripts/verify.sh <단계>다. 소유자 환경에서는 Gradle·Docker를 desktop에서만 돌린다:--on desktop을 붙이면 지금 작업 트리를 패치로 옮겨 잠금(/tmp/claude-gates/heavy.lock) 아래에서 돌린다. - 무엇을 돌릴지는
gates.md다. 완료를 말하기 전에 바꾼 것에 맞는 게이트를 돌리고, 못 돌렸으면 이유를 적는다.
3. 백엔드 템플릿과 같이 고치기
템플릿이 이 라이브러리를 버전으로 받게 되면(지금은 받지 않는다) 두 repo를 같이 바꾸는 일이 생긴다.
-
이 repo와 템플릿에 브랜치를 하나씩 만든다. 두 repo를 같은 부모 폴더에 둔다.
-
템플릿에서 명령 줄로만 이 repo를 끼운다. 파일은 바꾸지 않는다.
./gradlew --include-build ../grpc-library <태스크> -
그 상태로 lockfile을 쓰거나 커밋하지 않는다. 끼운 모듈은 lockfile 밖으로 빠질 수 있다.
-
병합 순서는 하나다: 이 repo PR 병합 → 태그·릴리스 → 템플릿 PR에서 버전을 올리고 lockfile을 다시 쓴다 → 템플릿 병합. 끼운 상태로만 통과하는 템플릿 PR은 병합하지 않는다.
-
공개 API를 바꾸는 PR은 본문에 템플릿 쪽 영향(끼운 상태로 돌린 태스크와 결과)을 적는다.
4. 이 repo에서 정한 것
- 결정 기록은
docs/adr/에 쌓는다. 템플릿에서 옮겨 온 ADR-GRPC-001~006·ADV-001은 번호를 그대로 둔다. 새 결정은docs/adr/0000-template.md양식으로ADR-GRPC-007부터 쓴다. - 문서는 한국어로 쓴다. 지난 결정을 고칠 때는 본문이 아니라 머리 블록의 「상태」·「현재 정본」만 고친다(
docs/README.md2절). - 커밋·PR 규칙은 design-docs
conventions/commit-and-pr.md다.main에는 PR로 넣는다(첫 커밋들만 예외였다).