SemVer 태그에서 GitHub Release와 홈페이지 반영까지

릴리스 자동화는 단계가 많아서 복잡해 보이지만, 실제로는 “어디가 기준인가”만 먼저 정하면 상당수가 정리됩니다. 이 강의에서는 GitHub Release 자체를 공개 릴리스의 canonical source로 둡니다. 그 결과 앱 저장소, 문서, 제품 페이지가 서로 다른 텍스트를 들고 따로 움직이는 문제를 줄일 수 있습니다.

그 다음으로 중요한 것은 homepage 저장소의 역할을 제한하는 것입니다. homepage는 source repo를 대신해 release를 만들거나 편집하지 않습니다. publish된 release를 읽어 와서 Astro content로 바꾸고, 자기 빌드와 커밋을 자기 토큰으로 끝내는 소비자 역할만 맡습니다. 이 책임 분리가 운영 안정성의 핵심입니다.

이 챕터에서는 전체 흐름을 먼저 고정해 두기 때문에, 뒤 챕터에서 나오는 secrets, generated notes, LLM polishing, dispatch token, import script가 모두 “어느 단계의 책임인가”로 다시 읽히게 됩니다. 즉 도구 설명보다 먼저 운영 경계를 잡는 챕터입니다.

SemVer 태그 자동화에서 가장 흔한 실수는 `v*`를 전부 같은 release로 취급하는 것입니다. 강의에서는 stable, beta, rc를 명시적으로 분리합니다. 이렇게 해야 prerelease 정책과 homepage sync 정책이 뒤에서 흔들리지 않습니다.

또 하나의 핵심은 release를 처음부터 public 상태로 만들지 않는 것입니다. draft release는 일종의 staging area입니다. asset 업로드, generated notes 재생성, 선택적 LLM polishing, 최종 title/body 정리까지 끝난 뒤에만 publish하게 두면 미완성 공개를 줄일 수 있습니다.

이 챕터는 recovery 경로도 함께 다룹니다. 이미 publish된 release를 기본적으로 다시 건드리지 않되, 정말 필요한 경우에만 `workflow_dispatch`와 별도 flag로 재실행을 허용하는 식입니다. 즉 자동화는 편의성뿐 아니라 실수의 기본 경로를 줄이는 도구라는 관점을 강조합니다.

기본값은 generated notes입니다. 이유는 간단합니다. GitHub가 compare 범위, PR 제목, contributor 정보를 이미 release 문맥 안에서 알고 있기 때문입니다. 따라서 초안 생성의 기준은 GitHub에 두고, 외부 LLM은 그 내용을 더 읽기 쉽게 다듬는 역할에만 제한하는 것이 안전합니다.

강의는 LLM을 “새 사실을 만드는 요약기”로 쓰지 않습니다. 오히려 구조화된 후처리기로 다룹니다. summary / highlights / fixes / notes 같은 섹션을 맞추되, 사실 추가 금지, 버전 문자열 보존, 링크와 식별자 보존을 강하게 요구합니다. 이렇게 해야 AI가 release의 사실 관계를 덮어쓰지 않습니다.

또한 이 챕터는 실패 정책을 같이 묻습니다. polishing이 실패했을 때 generated notes 그대로 publish할지, publish 전에 전체를 멈출지 결정해야 합니다. 이 선택은 문체보다 운영 철학의 문제이므로, 강의에서는 “사용자-facing release page의 일관성이 얼마나 중요한가”를 기준 질문으로 제시합니다.

사용자 입장에서는 GitHub Release 페이지보다 제품 홈페이지가 더 먼저 보일 수 있습니다. 그래서 release history를 GitHub 안에만 두지 않고 제품 페이지에서도 읽을 수 있게 만드는 것이 중요합니다. 하지만 앱 저장소가 homepage 저장소 파일을 직접 커밋하기 시작하면 권한과 책임이 빠르게 엉킵니다.

강의에서는 source repo가 homepage workflow만 깨우고, homepage repo가 자기 workflow 안에서 release를 조회해 Astro content 파일을 직접 생성하도록 둡니다. 즉 dispatch token은 “실행 요청”에만 쓰고, 실제 content 생성과 commit은 homepage의 `GITHUB_TOKEN`이 맡습니다. 이 구조가 권한 최소화의 핵심입니다.

또한 import script는 published stable release만 허용하도록 둡니다. draft, prerelease, unpublished 상태를 강하게 막아 두면 제품 페이지가 실수로 내부 릴리스 기록을 노출하는 문제를 줄일 수 있습니다. 이 챕터는 cross-repo automation에서도 “무엇을 허용하지 않을 것인가”가 얼마나 중요한지 보여 줍니다.

자동화는 “실행됐다”와 “검증됐다”가 다릅니다. GitHub Actions가 green이라고 해서 release body, homepage markdown, 제품 페이지가 모두 기대한 상태라는 뜻은 아닙니다. 그래서 이 챕터는 최소 네 층위의 검증을 명시합니다. 태그 판별, release 상태, homepage import, 사이트 렌더링입니다.

강의에서는 `gh run watch`, `gh release view`, import된 markdown 파일 확인, no-op 재실행까지 한 흐름으로 봅니다. 핵심은 사람이 마지막에 확인해야 하는 항목을 남겨 두는 것입니다. 특히 cross-repo sync에서는 “workflow가 돌았다”보다 “올바른 stable release 하나만 반영됐는가”가 더 중요합니다.

이 챕터는 운영 체크리스트를 남기는 이유도 설명합니다. 릴리스 자동화는 시간이 지나면 당연한 것처럼 보이지만, 실제 장애는 대부분 “이전엔 왜 이렇게 했는지”를 잊었을 때 발생합니다. 체크리스트는 단순 문서가 아니라 재발 방지 장치입니다.