diff --git a/docs/adr/0031-npm-native-distribution.md b/docs/adr/0031-npm-native-distribution.md index 72730f0..5becf27 100644 --- a/docs/adr/0031-npm-native-distribution.md +++ b/docs/adr/0031-npm-native-distribution.md @@ -54,7 +54,8 @@ OIDC를 사용한다. 이 job만 `id-token: write`를 가지며 npm password나 npm은 아직 존재하지 않는 package에 Trusted Publisher를 미리 연결할 수 없다. 그래서 실행 파일이 없는 `0.0.0-bootstrap.0` tarball 여섯 개를 사람이 검토한 뒤 npm 2FA로 한 번 게시한다. 그 다음 각 package의 -Trusted Publisher를 repository `PlateerLab/xgeny-cli`, workflow `release.yml`에 연결하고 +Trusted Publisher를 repository `PlateerLab/xgeny-cli`, workflow `release.yml`, environment 없음, +allowed action `npm publish`에 연결한다. Publishing access는 2FA를 요구하고 token publish를 금지한 뒤 `XGENY_NPM_PUBLISH_ENABLED=true`를 설정한다. Scope 또는 package 소유권을 확인할 수 없으면 release하지 않고 package 이름 계약부터 다시 결정한다. diff --git a/docs/development/npm-distribution.md b/docs/development/npm-distribution.md index b322788..a5d2fb9 100644 --- a/docs/development/npm-distribution.md +++ b/docs/development/npm-distribution.md @@ -51,7 +51,27 @@ node npm/scripts/bootstrap.mjs --output-dir "$bootstrap_dir" - repository: `xgeny-cli` - workflow filename: `release.yml` - environment: 사용하지 않음 -7. Package settings에서 write token을 추가하지 않았는지 확인하고 bootstrap version을 deprecated 처리한다. + - allowed actions: `npm publish`만 선택하고 `npm stage publish`는 선택하지 않음 + 2026-05-20 이후 생성하는 Trusted Publisher는 allowed action을 하나 이상 명시해야 한다. 현재 release + workflow는 직접 `npm publish`를 호출하므로 여섯 package 모두 위 선택이 같아야 한다. + + npm CLI 11.5.1 이상을 쓰면 npmjs.com의 동일 설정을 아래처럼 적용하고 즉시 다시 읽어 확인할 수 있다. + 이전 CLI를 유지해야 하면 package settings 화면에서 같은 값을 직접 설정한다. + +```bash +trusted_packages='@xgen/cli-linux-x64-musl @xgen/cli-linux-arm64-musl @xgen/cli-darwin-x64 @xgen/cli-darwin-arm64 @xgen/cli-win32-x64 @xgen/cli' +for package in $trusted_packages; do + npm trust github "$package" \ + --repository PlateerLab/xgeny-cli \ + --file release.yml \ + --allow-publish + npm trust list "$package" --json +done +``` + +7. Package settings의 Publishing access를 `Require two-factor authentication and disallow tokens`로 + 설정하고 write token을 추가하지 않았는지 확인한 뒤 bootstrap version을 deprecated 처리한다. + 이 설정은 GitHub OIDC Trusted Publisher를 막지 않는다. Package 자체는 unpublish하지 않는다. 8. GitHub repository variable `XGENY_NPM_PUBLISH_ENABLED=true`를 설정한다. 이 값은 여섯 package의 소유권과 Trusted Publisher 설정을 사람이 확인했다는 fail-closed acknowledgement다. diff --git a/docs/development/releasing.md b/docs/development/releasing.md index 6628459..d309664 100644 --- a/docs/development/releasing.md +++ b/docs/development/releasing.md @@ -31,8 +31,10 @@ binary를 감싸는 선택형 설치 채널이며 제품 runtime을 다시 구 `XGENY_RELEASE_RULESET_NO_BYPASS=true`를 설정한다. Read-only ruleset API는 bypass 목록을 숨길 수 있다. - npm의 `@xgen` scope에 여섯 package를 게시할 권한, 계정 2FA와 recovery 수단을 확인한다. 실행 파일이 없는 bootstrap version을 먼저 게시한 뒤 각 package의 Trusted Publisher를 repository - `PlateerLab/xgeny-cli`, workflow `release.yml`로 설정한다. 장기 npm token은 만들거나 GitHub secret에 - 저장하지 않는다. 전체 절차는 [npm 배포와 Trusted Publishing](npm-distribution.md)을 따른다. + `PlateerLab/xgeny-cli`, workflow `release.yml`, environment 없음, allowed action `npm publish`로 설정한다. + Publishing access는 `Require two-factor authentication and disallow tokens`로 제한한다. 장기 npm + token은 만들거나 GitHub secret에 저장하지 않는다. 전체 절차는 + [npm 배포와 Trusted Publishing](npm-distribution.md)을 따른다. - 여섯 package의 Trusted Publisher 설정을 확인한 뒤 repository variable `XGENY_NPM_PUBLISH_ENABLED=true`를 둔다. 값이 없거나 exact `true`가 아니면 native build 전에 release가 fail-closed한다. diff --git a/scripts/check-rc3-public-docs.sh b/scripts/check-rc3-public-docs.sh index 85de16d..a529524 100644 --- a/scripts/check-rc3-public-docs.sh +++ b/scripts/check-rc3-public-docs.sh @@ -19,6 +19,9 @@ candidate = (root / "docs/development/rc3-release-candidate.md").read_text( encoding="utf-8" ) security = (root / "SECURITY.md").read_text(encoding="utf-8") +npm_distribution = (root / "docs/development/npm-distribution.md").read_text( + encoding="utf-8" +) def require(document: str, fragments: tuple[str, ...], label: str) -> None: @@ -79,6 +82,19 @@ require( ), "SECURITY", ) +require( + npm_distribution, + ( + "allowed actions", + "`npm publish`만 선택", + "`npm stage publish`는 선택하지 않음", + "npm trust github", + "--allow-publish", + "npm trust list", + "Require two-factor authentication and disallow tokens", + ), + "npm-distribution", +) print("RC3 public documentation contract: PASS") PY