게시자 계정 설정

이 런북은 릴리스 표면의 게시자 측을 구성합니다. 배포에는 레지스트리가 하나뿐입니다. 바로 npmjs.com의 스코프 지정 npm 패키지 @ahmed-g-gad/apothem이며, 이 패키지는 publish-npm.yml 워크플로가 게시합니다. 이 워크플로는 v*.*.* 태그 푸시에서 release.yml과 나란히 실행되며 이를 기다리지 않습니다(tag 입력을 지정한 수동 디스패치가 대체 수단입니다). release 환경 승인이 게이트입니다. 운영자는 GitHub Release, Pages, CI, 적합성, 하니스 워크플로가 녹색이 된 후 이를 승인합니다. 다른 모든 아티팩트는 GitHub Release 페이지 자체로 배포되며 외부 게시자 계정이 필요 없습니다.

신원 매핑Copy Anchor Link

GitHub 소유자는 앞으로 바뀌어도 됩니다. 워크플로와 설치 프로그램 로직은 플랫폼이 동적 해석을 허용하는 곳에서 github.repository, github.repository_owner 또는 APOTHEM_GITHUB_REPO를 읽습니다. 사용자는 메인테이너 계정 이름이 아니라 패키지 이름을 설치하므로, 레지스트리 패키지 식별자는 안정적으로 유지됩니다.

npm (npmjs.com)Copy Anchor Link

1. ahmed-g-gad로 https://www.npmjs.com/에 로그인합니다.

2. 계정에서 2단계 인증을 활성화합니다.

3. 스코프 지정 패키지 이름을 확인합니다.

   Copy Text

   npm view @ahmed-g-gad/apothem name

   404는 스코프 지정 패키지가 아직 게시되지 않았다는 뜻입니다. 그 밖의 패키지 응답은 게시하기 전에 반드시 이 저장소 및 계정과 일치해야 합니다.

4. UI에서 첫 패키지 레코드가 필요하면 npm에서 패키지를 생성합니다. 이름은 스코프 지정 형태로 유지합니다: @ahmed-g-gad/apothem.

5. GitHub Actions에서 @ahmed-g-gad/apothem에 대한 Trusted Publishing을 구성합니다.

   • GitHub 소유자: ahmed-g-gad
   • 저장소: apothem
   • 워크플로 파일 이름: publish-npm.yml
   • 환경: release(publish-npm.yml에 있는 게시 작업의 environment:이며, 두 값은 일치해야 함)
   • 허용된 액션: npm publish.

6. GitHub에서 ahmed-g-gad/apothem에 release 환경이 존재하고 배포에 수동 승인이 필요한지 확인합니다.

7. npm 표면은 공개 레지스트리 패키지 하나로 유지합니다: npmjs.com의 @ahmed-g-gad/apothem.

8. 태그 푸시가 시작하는 release.yml 실행의 publish GitHub Release 작업을 승인합니다. 이 작업은 release 환경 승인을 기다리며, 아래 검사에는 그 실행이 녹색이어야 합니다. 방법은 릴리스 사이클 런북의 §2.3에서 안내합니다. 그런 다음 릴리스 준비 상태를 확인합니다.

   Copy Text

   bash scripts/release/check-release-ready.sh <release-tag>

   이 검사에는 GH_TOKEN이 설정되어 있고 게시된 sbom.cdx.json이 dist/release-assets/에 있어야 합니다. 릴리스 사이클 런북의 §2.4에서 토큰 범위와 다운로드 명령을 안내합니다.

9. 태그 푸시가 시작하는 Publish npm(publish-npm.yml) 실행에 대해 release 환경 배포를 승인합니다. 해당 실행이 시작되지 않았다면 GitHub Actions 탭에서 tag=<release-tag>로 워크플로를 디스패치합니다.

10. 라이브 패키지를 확인합니다.

    Copy Text

    npm view @ahmed-g-gad/apothem version
    npx @ahmed-g-gad/apothem@<version> --version

NPM_TOKEN, 사용자 이름, 비밀번호 시크릿은 필요하지 않습니다. 워크플로는 .github/workflows/publish-npm.yml 안에 고정된 Node 버전과 npm CLI OIDC 최저 버전으로 npm Trusted Publishing(OIDC)을 통해 게시합니다. 워크플로는 npmjs.com을 대상으로 npm publish --provenance --access public을 실행하므로 Sigstore 출처 진술이 명시적으로 지정되며, npm도 공개 GitHub Actions 워크플로에서 게시되는 공개 패키지에는 기본적으로 출처 진술을 내보냅니다. PUT 중의 레지스트리 404는 npm 측 신뢰할 수 있는 게시자, 패키지 스코프 또는 계정 권한이 아직 맞춰지지 않았다는 뜻입니다. 워크플로를 다시 시도하기 전에 npm 패키지 설정을 고치세요.

신뢰할 수 있는 게시가 한 번 성공하면 토큰 경로를 완전히 닫으세요. npmjs.com에서 패키지의 Settings → Publishing access로 이동해 Require two-factor authentication and disallow tokens를 선택하고, 저장소에 남아 있는 npm 토큰 시크릿을 모두 삭제합니다. 워크플로는 더 이상 토큰을 읽지 않습니다.

참고 자료: npm 신뢰할 수 있는 게시자, npm 출처 증명, npm 스코프.

GitHub 측 릴리스 전제 조건Copy Anchor Link

나머지 릴리스 표면은 GitHub 네이티브이며 저장소 범위의 GITHUB_TOKEN으로 인증합니다. 외부 계정은 관여하지 않습니다.

1. GitHub Release. .github/workflows/release.yml은 버전 태그에서 실행되며 작업 로컬 contents: write 권한만 필요합니다. 태그하기 전에 워크플로 파일이 main에 있는지 확인합니다.

2. Pages 사용자 지정 도메인. 문서 사이트는 publish-static-site.yml을 통해 사용자 지정 도메인 apothem.ahmedgad.com에 배포됩니다. 도메인, DNS, HTTPS 강제 적용은 Pages 활성화 런북이 마련합니다. 다음으로 확인합니다.

   Copy Text

   gh api repos/ahmed-g-gad/apothem/pages --jq '.cname, .https_enforced'
   curl -sSI https://apothem.ahmedgad.com/ | head -n 1

3. 스크립트 설치 프로그램. install.sh와 install.ps1은 Pages 사이트에서 제공됩니다(https://apothem.ahmedgad.com/install.sh와 https://apothem.ahmedgad.com/install.ps1). 같은 Pages 배포가 이 파일들을 게시하며, 별도의 계정이나 토큰은 필요하지 않습니다.

검증 매트릭스Copy Anchor Link

설정 후 각 게시자 표면은 자신의 정식 검사에 응답합니다.