AkiGarage/safe-public-github-release

안전한 공개 GitHub 릴리스

핵심 규칙

속도보다 공개 신뢰를 우선시하세요. 깨끗한 공개 스냅샷, 릴리스 브랜치 PR/CI 게이트, 검증된 GitHub 릴리스 아티팩트, 체크섬, 그리고 돌이킬 수 없는 작업에 대한 명시적인 유지보수자 승인을 선호합니다.

개인 이력을 그 자리에서 공개하지 마세요. 깨끗한 공개 스냅샷으로 생성되어 최종 다듬기 위해서만 비공개로 유지된 저장소는 최종 스크럽 게이트를 통과한 후에 공개로 전환할 수 있습니다. PyPI/TestPyPI는 Python 패키지 배포가 실제로 범위 내에 있을 때만 사용하세요.

워크플로우

1. 먼저 검사하세요:
   • git status -sb, 리모트, 현재 브랜치, 태그, 관련 워크플로우.
   • gh를 사용하여 공개 저장소 가시성, 기본 브랜치, 릴리스/태그 상태, GitHub 환경.
   • 설치 경로, 게시, Homebrew, TestPyPI, PyPI, 개인 저장소, 로컬 경로, 또는 핸드오프 파일을 언급하는 기존 문서.
2. 공개 표면의 범위를 정하세요:
   • 공개 문서 및 패키지 메타데이터는 공개 소유자/저장소, 패키지 이름, 공개 태그, 공식 설치 명령어를 언급할 수 있습니다.
   • 공개 문서는 개인 저장소 이름, 로컬 홈 경로, HANDOFF.md, CONTINUITY.md, .local, .codex, 토큰, 키, 원시 내부 기록, 또는 유지보수자 전용 지침을 공개 지침으로 다시 작성하지 않는 한 언급해서는 안 됩니다.
   • 저장소-로컬 문서 및 미디어에는 상대적인 README 링크를 선호하세요. 릴리스 노트에서 절대 GitHub 소유자/저장소 URL은 괜찮지만, README에서는 불필요한 소유자 결합 및 공개 표면 스크럽 검사의 오탐지를 만들 수 있습니다.
3. GitHub 릴리스 게이트를 준비하세요:
   • 원격 변경 전에 로컬에서 빌드/테스트하세요.
   • 기본적으로 release/vX.Y.Z -> PR -> CI -> 병합 순서를 태깅 전에 사용하세요.
   • README 또는 지역화된 README 파일이 변경될 때 병합 전에 Aki의 GitHub-렌더링 README 시각적 승인이 필요합니다.
   • 업로드 전에 릴리스 자산을 확인하세요: 예상 파일 이름, 버전 메타데이터, 체크섬, 아카이브 내용, 해당되는 경우 플랫폼별 서명/공증 확인.
   • macOS .app zip 자산의 경우, AppleDouble 또는 Finder 메타데이터 없이 아카이브를 빌드하세요. COPYFILE_DISABLE=1 zip 또는 동등한 아카이브 명령을 선호하고, __MACOSX, .DS_Store, 또는 ._* 파일이 포함된 아카이브는 거부하세요. 이러한 추가 파일은 압축 해제 후 서명된 앱의 확인을 실패하게 만들 수 있습니다.
   • 업로드될 정확한 아카이브를 임시 디렉토리에 추출하고, 앱/패키지 버전 메데이터를 확인하고, 추출된 페이로드에서 관련 서명/공증 확인을 실행하여 항상 확인하세요.
4. GitHub 릴리스를 다음 순서로 게시하세요:
   • main을 다시 가져오고, 최신 CI가 녹색인지 확인하고, 로컬 작업 트리가 깨끗한지 확인하세요.
   • 대상 태그와 GitHub 릴리스가 이미 존재하지 않는지 확인하세요.
   • 확인된 main 커밋에 태그를 만드세요.
   • 태그를 푸시하세요.
   • dist/...와 같은 로컬 경로가 아닌 릴리스-지향 기준 이름을 사용하여 최종 업로드 파일에서 체크섬 파일을 만드세요.
   • 의도된 노트와 의도된 자산만으로 GitHub 릴리스를 만드세요.
   • 자산 유형에 유용한 경우 체크섬 파일을 업로드하고, 사용자가 다운로드를 확인하는 데 도움이 될 때 릴리스 노트에 체크섬을 포함하세요.
5. GitHub 게시 후 확인하세요:
   • 태그가 예상 커밋을 가리키는지 확인하세요.
   • GitHub 릴리스가 예상 URL에서 볼 수 있는지 확인하세요.
   • 릴리스 자산과 체크섬이 로컬에서 확인된 파일과 일치하는지 확인하세요.
   • 게시된 릴리스 자산을 임시 디렉토리에 다운로드하고 다운로드된 복사본에서 확인하세요. 체크섬 지원 아카이브의 경우 shasum -a 256 -c <asset>.sha256을 실행하고, macOS .app zip의 경우 다운로드한 자산의 압축을 풀고 추출된 앱에서 앱 버전 및 codesign --verify --strict --deep 검사를 실행하세요.
   • 공개 README/문서가 라이브 릴리스 버전 및 자산 이름과 일치하는지 확인하세요.

선택적 PyPI / TestPyPI 하위 섹션

이 하위 섹션은 GitHub 릴리스가 Python 패키지, CLI, 또는 uvx 설치 경로도 게시하는 경우에만 사용하세요.

1. testpypi 및 pypi에 대한 GitHub 환경이 있는지 확인하세요.
2. pypi를 유지보수자 승인 뒤에 두세요.
3. 저장된 PyPI 토큰 대신 id-token: write 및 PyPI 신뢰할 수 있는 게시자를 사용하세요.
4. 다음 순서로 게시하세요:
   • 의도된 태그에서 빌드 전용 워크플로우.
   • SHA256SUMS 및 아티팩트 증명이 포함된 GitHub 릴리스 아카이브.
   • TestPyPI 게시, 그런 다음 설치 스모크 테스트.
   • TestPyPI가 버전을 보여주고 설치 스모크가 통과한 후에만 PyPI 게시.
   • 라이브 설치 경로를 기본으로 만들기 위한 문서 업데이트.
5. 게시 후 확인:
   • PyPI/TestPyPI JSON에 예상 버전이 포함되어 있는지 확인하세요.
   • uvx --from <package> <command> --help가 작동하는지 확인하세요.
   • 동일한 버전을 다시 업로드하는 것이 준비 검사에 의해 차단되는지 확인하세요.
   • 공개 README/문서가 라이브 설치 경로와 일치하는지 확인하세요.

GitHub 전용 공개 스냅샷 체크리스트

대상이 PyPI 없이 GitHub 저장소 또는 앱 릴리스인 경우 이것을 사용하세요.

1. 최종 게이트가 통과할 때까지 저장소를 비공개로 유지하세요. 공개 대상이 별도의 이미 공개된 저장소인 경우 개인 기록을 절대 복사하지 말고 스크럽된 스냅샷 콘텐츠만 이동하세요.
2. 공개 스냅샷에 대해 기본적으로 릴리스 브랜치와 PR을 사용하세요:
   • 공개 저장소에서 release/vX.Y.Z를 생성하거나 업데이트하세요.
   • 해당 브랜치에 준비된 스냅샷 및 공개 문서를 커밋하세요.
   • main에 PR을 열고 CI가 거기서 실행되도록 하세요.
   • README 또는 릴리스-지향 문서가 변경되는 경우 readme-release-sync를 사용하여 공개 복사본이 읽기 쉽고, 이중 언어로 유지되며, 출시된 동작과 일치하도록 하세요.
   • Aki에게 PR/브랜치에 대한 GitHub-렌더링 README 링크를 제공하고 병합 전에 명시적인 시각적 승인을 기다리세요. 로컬 마크다운 미리보기, 원시 파일 보기, 스크린샷 또는 자동화된 링크 검사는 이 게이트를 대체하지 않습니다.
   • CI가 녹색이고 공개 표면 스크럽이 통과한 후에만 병합하세요.
   • Aki가 PR 게이트를 건너뛰도록 명시적으로 요청하는 경우에만 main에 직접 푸시하세요.
3. 작업 트리뿐만 아니라 추적된 파일을 스크럽하세요:
   • 비밀, 로컬 경로, 유지보수자 이름, 이전 개인 저장소 이름, 핸드오프 파일, 생성된 아카이브, 오래된 제품 이름.
   • git ls-files로 우발적인 .mov, .mp4, 빌드 출력, 캐시, 큰 바이너리 파일을 확인하세요.
4. README 미디어를 공개 표면의 일부로 취급하세요:
   • 인라인 GIF는 가장 신뢰할 수 있는 GitHub README 데모 형식입니다. GitHub의 실제 이미지/GIF 제한 미만으로 유지하세요.
   • 로컬 README <video> 임베드 및 저장소-로컬 MP4 미리보기 링크는 실패하거나 불안정한 GitHub 파일-미리보기 페이지를 열 수 있습니다.
   • 선택적 MP4 데모는 정말로 필요한 경우에만 GitHub 릴리스 자산에 넣고, 제품에 필요하지 않으면 릴리스 노트 참조와 함께 제거하세요.
5. 태그 또는 GitHub 릴리스를 만들기 전에 다시 가져오세요:
   • 병합 후 main의 PR 병합 상태 및 최신 CI 상태
   • git status -sb, git log --oneline -1, git tag --list, 현재 릴리스 자산
   • 저장소가 이미 공개된 경우 GitHub 콘텐츠 API를 통한 README 및 참조된 이미지 경로
   • 모든 바이너리 업로드에 대한 아카이브 내용 및 추출된 자산 확인 결과
6. 가시성을 전환하기 전에 다시 가져오세요:
   • gh repo view ... --json visibility,isPrivate,url,defaultBranchRef
   • 기본 브랜치에 대한 최신 Actions 상태
   • 릴리스 자산 및 릴리스 노트
   • GitHub 콘텐츠 API를 통한 README 및 참조된 이미지 경로
7. Aki가 게시하라고 명시적으로 말한 후에만 가시성을 전환하고, visibility=PUBLIC, 공개 README URL 가용성, 릴리스 자산, 깨끗한 로컬 작업 트리를 확인하세요.

깨끗한 스냅샷을 공개 저장소로 이동하는 흐름

개인/내부 저장소가 별도의 공개 저장소에 공급하는 경우 이 흐름을 사용하세요.

1. 개인 저장소에서 기능을 완료하고 검증하세요.
2. 공개 파일의 허용 목록에서 임시 스냅샷 폴더를 만드세요.
3. 스냅샷에 공개 이름을 적용하고 개인 전용 표면을 제거하세요.
4. 스냅샷에서 비밀, 개인 경로, 핸드오프 파일, 이전 제품 이름, 생성된 아카이브, 큰 우발적 파일을 스크럽하세요.
5. 스크럽된 스냅샷을 공개 저장소 작업 트리에 복사하세요.
6. release/vX.Y.Z를 만들거나 전환하세요.
7. 해당 브랜치에서 공개 README, 지역화된 README, 변경 로그, 버전 메데이터, 릴리스 초안 노트, README 미디어 참조를 업데이트하세요.
8. git diff, README 미디어 링크, 이중 언어 패리티, 오래된 표현, 공개 표면 스캔 결과를 검사하세요.
9. 관련 로컬 빌드/테스트/패키지 검사를 실행하세요.
10. release/vX.Y.Z에 릴리스 준비 변경 사항을 커밋하고 브랜치를 푸시하세요.
11. main에 PR을 여세요. 아직 태그를 만들거나 GitHub 릴리스를 생성하지 마세요.
12. CI를 기다리고, 릴리스 브랜치에서 실패를 수정하고, 검사를 다시 실행하세요.
13. Aki에게 PR/브랜치의 README.md 및 지역화된 README 파일에 대한 GitHub-렌더링 README URL을 보내세요. GitHub에서 README가 올바르게 보인다는 명시적인 시각적 승인을 기다리세요.
14. CI, 스크럽 게이트, Aki의 GitHub-렌더링 README 시각적 승인이 모두 통과한 후에만 PR을 병합하세요.
15. main을 다시 가져오고 병합된 커밋이 깨끗하고 녹색인지 확인하세요.
16. vX.Y.Z를 만들거나, 자산을 업로드하거나, GitHub 릴리스를 생성/게시하기 전에 Aki 승인을 위해 중단하세요.

아직 공개 저장소가 없는 경우의 흐름

프로젝트에 공개 저장소가 없었던 경우 이 경로를 사용하세요.

1. 개인/내부 작업 저장소를 공개로 전환하지 마세요.
2. 새롭고 깨끗한 게시 저장소를 만들고 처음에는 비공개로 유지하세요.
3. 개인 기록이 아닌 스크럽된 공개 스냅샷에서만 초기화하세요.
4. 처음부터 공개 지향 제품 이름, 패키지 메데이터, README 파일, 라이선스, 변경 로그, 릴리스 초안 노트, 스크린샷/GIF, 워크플로우를 사용하세요.
5. 추적된 파일에서 동일한 비밀/개인 경로/큰 파일/공개 표면 스크럽을 실행하세요.
6. 저장소가 여전히 비공개이더라도 release/vX.Y.Z -> PR -> CI -> Aki GitHub-렌더링 README 시각적 승인 -> 병합을 사용하세요.
7. 가능하면 저장소가 여전히 비공개인 동안 의도된 태그와 GitHub 릴리스 초안을 만들고 거기서 자산/체크섬을 확인하세요.
8. 가시성을 변경하기 전에 Aki 승인을 위해 중단하세요.
9. 최종 스크럽, 녹색 CI, 의도된 릴리스 자산, 명시적인 Aki 승인 후에만 가시성을 공개로 전환하세요.
10. 가시성 전환 후 공개 README 가용성, 릴리스 자산, 태그, 최신 Actions 상태, 로컬 깨끗한 작업 트리를 다시 가져와 확인하세요.

중요한 교훈

• GitHub Actions 워크플로우 정의는 워크플로우를 디스패치하는 데 사용된 참조에서 가져옵니다. 새 워크플로우 입력 또는 가드가 추가되기 전에 태그가 생성된 경우, 해당 이전 태그에서 디스패치하면 새 입력을 알 수 없습니다.
• 향후 릴리스에서는 태그를 생성하기 전에 릴리스 가드를 배치해야 합니다. 그런 다음 보호된 입력으로 해당 태그에서 디스패치하세요.
• 일회성 기록 태그가 가드보다 이전인 경우 추측하지 마세요. 로컬 준비 검사를 실행하고, 먼저 TestPyPI를 증명하고, 아티팩트/증명을 확인하고, 예외를 문서화하세요.
• 릴리스 자산 위생은 중요합니다: 탐색적 업로드 후 최종 공개 릴리스에는 의도된 아티팩트만 포함되어야 합니다. 게시하기 전에 원하지 않는 자산을 삭제하고 해당 SHA 줄 또는 릴리스 노트 언급을 제거하세요.

상세 실행 가이드

단계별 체크리스트, 명령 패턴, 공개 문서 감사 패턴은 references/pypi-trusted-release-runbook.md를 읽으세요.