2 files changed
+76
-7
.agents/skills/smbcloud-cli-release/SKILL.md
+64
@@ -97,6 +97,70 @@ When that happens, retry the exact `npm publish` command with:
97
98
Do not assume the first publish failed before the package upload step. Check the exit result or npm registry state before retrying repeatedly.
99
100
+## Trusted publishing
101
+
102
+Prefer npm trusted publishers for CI over `NPM_TOKEN`.
103
+
104
+Official references:
105
+
106
+- https://docs.npmjs.com/trusted-publishers/
107
+- https://docs.npmjs.com/cli/v11/commands/npm-trust/
108
+
109
+### npm-side constraints
110
+
111
+Trusted publishing can only be configured for packages that already exist on npm.
112
+
113
+That means:
114
+
115
+- publish a package once manually if it does not exist yet
116
+- then configure trust for that package
117
+- each package can have only one trusted publisher configuration at a time
118
+
119
+For `smbcloud-cli`, configure trust per package, not only for `@smbcloud/cli`.
120
+
121
+Example packages:
122
+
123
+- `@smbcloud/cli`
124
+- `@smbcloud/cli-darwin-arm64`
125
+- later, each additional published `@smbcloud/cli-*` package
126
+
127
+### GitHub Actions setup
128
+
129
+The workflow must include:
130
+
131
+- `permissions:`
132
+- `id-token: write`
133
+- `contents: read`
134
+
135
+Do not pass `NODE_AUTH_TOKEN` to `npm publish` when using trusted publishing.
136
+
137
+The npm CLI detects the GitHub OIDC environment automatically and exchanges it for a short-lived publish credential.
138
+
139
+### Trusted publisher command
140
+
141
+For this repo, the trust relationship should point at:
142
+
143
+- repository: `smbcloudXYZ/smbcloud-cli`
144
+- workflow file: `release-npm.yml`
145
+
146
+Example:
147
+
148
+- `npm trust github @smbcloud/cli --repo smbcloudXYZ/smbcloud-cli --file release-npm.yml --yes`
149
+- `npm trust github @smbcloud/cli-darwin-arm64 --repo smbcloudXYZ/smbcloud-cli --file release-npm.yml --yes`
150
+
151
+These commands may require npm 2FA and support `--otp=<code>`.
152
+
153
+### Migration guidance
154
+
155
+Recommended order:
156
+
157
+1. enable trusted publishing for existing packages
158
+2. verify a CI publish works through OIDC
159
+3. then remove or stop using `NPM_TOKEN`
160
+4. after the migration is proven, tighten npm package publishing access if desired
161
+
162
+Do not remove the manual publish path for brand-new package names, because npm trust cannot be configured before the first publish.
163
+
164
## CI/CD workflow rules
165
166
The release workflow lives in `.github/workflows/release-npm.yml`.
.github/workflows/release-npm.yml
+12
-7
@@ -6,6 +6,10 @@ on:
6
- "v*.*.*"
7
workflow_dispatch:
8
9
+permissions:
10
+ id-token: write
11
+ contents: read
12
+
13
env:
14
SMB_CLIENT_ID: ${{ secrets.SMB_CLIENT_ID }}
15
SMB_CLIENT_SECRET: ${{ secrets.SMB_CLIENT_SECRET }}
@@ -77,10 +81,15 @@ jobs:
81
echo "RELEASE_VERSION=${release_version}" >> "$GITHUB_ENV"
82
83
- name: Install toolkit
80
- uses: dtolnay/rust-toolchain@master
84
+ uses: dtolnay/rust-toolchain@3c5f7ea28cd621ae0bf5283f0e981fb97b8a7af9
85
with:
82
- targets: ${{ matrix.build.TARGET }}
83
- toolchain: ${{ matrix.build.TOOLCHAIN}}
86
+ toolchain: ${{ matrix.build.TOOLCHAIN }}
87
+
88
+ - name: Install Rust target
89
+ shell: bash
90
+ run: |
91
+ rustup target add ${{ matrix.build.TARGET }} --toolchain ${{ matrix.build.TOOLCHAIN }}
92
+ rustup target list --installed
93
94
- name: Create .env file
95
run: |
@@ -143,8 +152,6 @@ jobs:
152
# publish the package
153
cd "${node_pkg}"
154
npm publish --access public
146
- env:
147
- NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
155
156
publish-npm-base:
157
name: Publish the base NPM package
@@ -181,5 +188,3 @@ jobs:
188
npm install
189
npm run build
190
npm publish --access public
184
- env:
185
- NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}