feat: add approval-gated npm release workflows

.changeset/pre.json

@@ -1,5 +1,5 @@
 {
-	"mode": "pre",
+	"mode": "exit",
 	"tag": "beta",
 	"initialVersions": {
 		"@openagentpack/server": "0.0.1",

.github/CODEOWNERS

@@ -1,12 +1,12 @@
 # Core infrastructure requires maintainer review.
-/.github/                          @modelstudioai/openagentpack-maintainers
-/scripts/                          @modelstudioai/openagentpack-maintainers
-/package.json                      @modelstudioai/openagentpack-maintainers
-/bun.lock                          @modelstudioai/openagentpack-maintainers
+/.github/                          @heimanba
+/scripts/                          @heimanba
+/package.json                      @heimanba
+/bun.lock                          @heimanba
 
 # Workspace package boundaries.
-/packages/sdk/src/internal/providers/interface.ts     @modelstudioai/openagentpack-maintainers
-/packages/sdk/src/internal/providers/capabilities.ts  @modelstudioai/openagentpack-maintainers
-/packages/sdk/src/internal/providers/registry.ts      @modelstudioai/openagentpack-maintainers
-/packages/sdk/src/internal/providers/base-client.ts   @modelstudioai/openagentpack-maintainers
-/packages/sdk/src/internal/types/                     @modelstudioai/openagentpack-maintainers
+/packages/sdk/src/internal/providers/interface.ts     @heimanba
+/packages/sdk/src/internal/providers/capabilities.ts  @heimanba
+/packages/sdk/src/internal/providers/registry.ts      @heimanba
+/packages/sdk/src/internal/providers/base-client.ts   @heimanba
+/packages/sdk/src/internal/types/                     @heimanba

.github/workflows/prepare-beta.yml

@@ -0,0 +1,81 @@
+name: Prepare Beta Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Stable SemVer series, for example 0.1.0
+        required: true
+        type: string
+
+concurrency:
+  group: prepare-beta-${{ inputs.version }}
+  cancel-in-progress: false
+
+jobs:
+  prepare:
+    if: github.ref_name == 'main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          fetch-depth: 0
+
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+        with:
+          bun-version: "1.3.5"
+
+      - name: Validate requested version
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::version must be a stable SemVer such as 0.1.0"
+            exit 1
+          fi
+
+      - name: Prepare isolated beta branch
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          branch="release/${VERSION}-beta"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git fetch origin main
+          if git ls-remote --exit-code --heads origin "${branch}" >/dev/null 2>&1; then
+            git fetch origin "${branch}"
+            git checkout --branch "${branch}" --track "origin/${branch}"
+            git merge --no-edit origin/main
+          else
+            git checkout --branch "${branch}" origin/main
+            bunx changeset pre enter beta
+          fi
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Calculate next beta version
+        run: bun run release:version
+
+      - name: Validate calculated beta version
+        id: release
+        run: >-
+          bun run scripts/release/channel.ts validate
+          --channel beta
+          --ref "release/${{ inputs.version }}-beta"
+          --expected "${{ inputs.version }}"
+          --output "$GITHUB_OUTPUT"
+
+      - name: Commit and push beta branch
+        env:
+          VERSION: ${{ steps.release.outputs.version }}
+        run: |
+          if git diff --quiet && git diff --cached --quiet; then
+            echo "::error::No unreleased changesets are available for the next beta."
+            exit 1
+          fi
+          git add --all
+          git commit --message "chore: prepare ${VERSION}"
+          git push origin HEAD

.github/workflows/release-pr.yml

@@ -0,0 +1,36 @@
+name: Release PR
+
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: release-pr
+  cancel-in-progress: false
+
+jobs:
+  version:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          fetch-depth: 0
+
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+        with:
+          bun-version: "1.3.5"
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Create or update stable Release PR
+        uses: changesets/action@a45c4d594aa4e2c509dc14a9f2b3b67ba3780d0d # v1.9.0
+        with:
+          version: bun run release:version
+          commit: "chore: release packages"
+          title: "chore: release packages"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -1,27 +1,34 @@
-name: Release
+name: Publish npm
 
 on:
   workflow_dispatch:
-  push:
-    branches: [main]
+    inputs:
+      channel:
+        description: npm channel to publish
+        required: true
+        type: choice
+        options:
+          - beta
+          - stable
+      confirm:
+        description: Type PUBLISH to confirm
+        required: true
+        type: string
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
   # Publishing three packages is not atomic. Never cancel a run after the first
-  # package may already have reached npm; the publish script is also idempotent
-  # so a failed run can safely be retried.
+  # package may already have reached npm; exact versions are safe to retry.
+  group: npm-publish
   cancel-in-progress: false
 
 jobs:
-  release:
-    # Missing repository variables resolve to an empty string, so a newly
-    # created repository cannot publish until maintainers explicitly opt in.
-    if: vars.NPM_RELEASE_ENABLED == 'true'
+  publish:
+    if: vars.NPM_RELEASE_ENABLED == 'true' && inputs.confirm == 'PUBLISH'
     runs-on: ubuntu-latest
+    environment: npm-release
     permissions:
       contents: write
       id-token: write
-      pull-requests: write
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
         with:
@@ -43,22 +50,48 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
+      - name: Validate channel, branch, and package versions
+        id: release
+        run: >-
+          bun run scripts/release/channel.ts validate
+          --channel "${{ inputs.channel }}"
+          --ref "${{ github.ref_name }}"
+          --output "$GITHUB_OUTPUT"
+
       - name: Verify release
-        env:
-          BASE: ${{ github.event.before }}
         run: bun run verify:release
 
-      - name: Create Release PR or Publish
-        uses: changesets/action@a45c4d594aa4e2c509dc14a9f2b3b67ba3780d0d # v1.9.0
-        with:
-          version: bun run release:version
-          publish: bun run release:publish
-          commit: "chore: release packages"
-          title: "chore: release packages"
+      - name: Publish packages with npm Trusted Publishing
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Bootstrap only: set this secret for the first publication, then remove
-          # and revoke it after npm Trusted Publishers are configured. With the
-          # secret absent, npm authenticates through OIDC trusted publishing.
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
           NPM_CONFIG_PROVENANCE: "true"
+        run: bun run release:publish
+
+      - name: Create immutable Git tag
+        env:
+          VERSION: ${{ steps.release.outputs.version }}
+        run: |
+          tag="v${VERSION}"
+          if git rev-parse --verify --quiet "refs/tags/${tag}"; then
+            test "$(git rev-list -n 1 "${tag}")" = "$GITHUB_SHA" || {
+              echo "::error::${tag} already points to another commit"
+              exit 1
+            }
+          else
+            git tag --annotate "${tag}" --message "${tag}"
+            git push origin "${tag}"
+          fi
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.release.outputs.version }}
+          CHANNEL: ${{ steps.release.outputs.channel }}
+        run: |
+          tag="v${VERSION}"
+          if gh release view "${tag}" >/dev/null 2>&1; then
+            echo "GitHub Release ${tag} already exists; nothing to do."
+          elif test "${CHANNEL}" = beta; then
+            gh release create "${tag}" --verify-tag --generate-notes --prerelease --title "${tag}"
+          else
+            gh release create "${tag}" --verify-tag --generate-notes --title "${tag}"
+          fi

CONTRIBUTING.md

@@ -8,7 +8,7 @@ Thanks for your interest in improving OpenAgentPack. By participating you agree
 |-------|-----|
 | Dev setup, verification, package boundaries | [docs/contributing/development.md](./docs/contributing/development.md) |
 | Adding a new provider | [docs/contributing/provider-development.md](./docs/contributing/provider-development.md) |
-| npm release workflow | [docs/contributing/release.md](./docs/contributing/release.md) |
+| npm release workflow | [English](./docs/contributing/release.md) · [简体中文](./docs/contributing/release.zh-CN.md) |
 | Architecture and how it works | [docs/architecture/how-it-works.md](./docs/architecture/how-it-works.md) |
 
 ## Quick start

README.md

@@ -136,6 +136,7 @@ npm install -g @openagentpack/cli
 ```
 
 This provides the `agents` command. To run from source instead, see [Contributing](./CONTRIBUTING.md).
+Beta testers can install `@openagentpack/cli@beta`; see the [release guide](./docs/contributing/release.md#what-users-install) for version pinning and switching back to stable.
 
 ## Provider support
 

README.zh-CN.md

@@ -136,6 +136,7 @@ npm install -g @openagentpack/cli
 ```
 
 安装后即可使用 `agents` 命令。若想从源码运行，见 [贡献指南](./CONTRIBUTING.md)。
+Beta 用户可以安装 `@openagentpack/cli@beta`；固定版本及切回稳定版的方法见 [发布指南](./docs/contributing/release.zh-CN.md#用户如何安装)。
 
 ## Provider 支持