Skip to content

Commit bbf6724

Browse files
MichaelEakinsMichaelEakins
committed
docs: add comprehensive Trusted Publishing setup guide
Complete documentation for npm Trusted Publishing (OIDC): - Setup instructions and configuration - Release process automation - Security workflows overview - Troubleshooting common issues - Verification and monitoring - Migration notes from token-based publishing Refs: #documentation #trusted-publishing #oidc
1 parent 15f3bfa commit bbf6724

1 file changed

Lines changed: 332 additions & 0 deletions

File tree

‎TRUSTED-PUBLISHING-SETUP.md‎

Lines changed: 332 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,332 @@
1+
# npm Trusted Publishing Setup Guide
2+
3+
This package uses **npm Trusted Publishing** (OIDC) for secure, token-free releases with cryptographic provenance.
4+
5+
## ✅ What We Have
6+
7+
**Package**: `@crashbytes/react-version-compare`
8+
**Version**: 1.0.4
9+
**Published**: 2026-01-14 06:02 UTC
10+
**Provenance**: https://search.sigstore.dev/?logIndex=820833331
11+
**GitHub Release**: https://github.com/CrashBytes/react-version-compare/releases/tag/v1.0.4
12+
13+
## 🔐 Security Features
14+
15+
- **No tokens required** - Uses OIDC authentication via GitHub Actions
16+
- **Cryptographic provenance** - Every release includes verifiable supply chain attestation
17+
- **Sigstore transparency** - All releases logged in public transparency log
18+
- **Automated security** - Weekly audits, dependency updates, CodeQL scanning
19+
- **React compatibility** - Automated testing against React 18 & 19
20+
21+
## 📋 npm Trusted Publisher Configuration
22+
23+
**Organization**: `CrashBytes` (case-sensitive!)
24+
**Repository**: `react-version-compare`
25+
**Workflow**: `release.yml`
26+
**Environment**: (blank/empty)
27+
28+
**⚠️ CRITICAL**: The Environment field MUST be blank unless using GitHub Environments!
29+
30+
## 🚀 Release Process
31+
32+
### Automated Tag-Based Releases
33+
34+
1. **Update version** in `package.json`:
35+
```bash
36+
# Edit package.json, change version to 1.0.5
37+
```
38+
39+
2. **Update CHANGELOG.md** with release notes
40+
41+
3. **Commit and tag**:
42+
```bash
43+
git add package.json CHANGELOG.md
44+
git commit -m "chore: release v1.0.5"
45+
git tag v1.0.5
46+
```
47+
48+
4. **Push** (triggers automatic release):
49+
```bash
50+
git push origin main && git push origin v1.0.5
51+
```
52+
53+
5. **Monitor workflow**:
54+
```bash
55+
gh run list --workflow=release.yml --limit 1
56+
gh run watch <run-id>
57+
```
58+
59+
### What Happens Automatically
60+
61+
When you push a tag (e.g., `v1.0.5`):
62+
63+
1. ✅ Checkout code
64+
2. ✅ Setup Node.js 20
65+
3. ✅ Upgrade npm to latest (≥ 11.5.1 for OIDC)4. ✅ Install dependencies
66+
5. ✅ Build package
67+
6. ✅ Run tests
68+
7. ✅ Type check
69+
8. ✅ **Publish to npm with provenance** (OIDC - no tokens!)
70+
9. ✅ Create GitHub Release
71+
10. ✅ Cryptographic attestation logged to Sigstore
72+
73+
**Total time**: ~45-60 seconds
74+
75+
## 🔍 Verifying Releases
76+
77+
### Check Package Version
78+
```bash
79+
npm view @crashbytes/react-version-compare version
80+
```
81+
82+
### Verify Provenance
83+
```bash
84+
npm view @crashbytes/react-version-compare dist.integrity
85+
```
86+
87+
### View on npm
88+
https://www.npmjs.com/package/@crashbytes/react-version-compare
89+
90+
### View Sigstore Transparency Log
91+
Each release includes a link like:
92+
https://search.sigstore.dev/?logIndex=820833331
93+
94+
## 🛡️ Security Workflows
95+
96+
### 1. Security Audit (`.github/workflows/security-audit.yml`)
97+
- **Trigger**: Push, PR, weekly schedule, manual
98+
- **What it does**:
99+
- npm audit (all dependencies)
100+
- npm audit (production only)
101+
- CodeQL analysis (JavaScript + TypeScript)
102+
- Dependency review (PRs only)
103+
104+
### 2. React Compatibility (`.github/workflows/react-compat.yml`)
105+
- **Trigger**: Push, PR, weekly schedule, manual
106+
- **What it does**:
107+
- Test against React 18
108+
- Test against React 19
109+
- Validates peer dependency compatibility
110+
111+
### 3. Dependabot (`.github/dependabot.yml`)
112+
- **Schedule**: Weekly (Mondays 9 AM UTC)
113+
- **Groups dependencies** by type:
114+
- Production dependencies
115+
- Development dependencies
116+
- Testing dependencies (@testing-library, jest)
117+
- Build tools (rollup, typescript, vite)
118+
- **Auto-assigns** PRs to MichaelEakins
119+
## 🐛 Troubleshooting
120+
121+
### Error: `ENEEDAUTH`
122+
123+
**Symptoms**:
124+
```
125+
npm error code ENEEDAUTH
126+
npm error need auth This command requires you to be logged in
127+
```
128+
129+
**Causes & Solutions**:
130+
131+
1. **Wrong repository name** in npm config
132+
- ❌ Bad: `compare`
133+
- ✅ Good: `react-version-compare`
134+
135+
2. **Wrong workflow filename** in npm config
136+
- ❌ Bad: `publish.yml`
137+
- ✅ Good: `release.yml`
138+
139+
3. **Environment name not blank**
140+
- ❌ Bad: "main", "production", etc.
141+
- ✅ Good: (completely empty field)
142+
143+
4. **Wrong organization case**
144+
- ❌ Bad: `crashbytes`, `crashBytes`
145+
- ✅ Good: `CrashBytes` (exact case!)
146+
147+
5. **npm CLI too old**
148+
- Solution: Workflow automatically upgrades to latest npm (≥ 11.5.1)
149+
150+
6. **registry-url in workflow**
151+
- Solution: Remove `registry-url` from `setup-node` step
152+
- OIDC doesn't use .npmrc authentication
153+
154+
### Error: Workflow doesn't trigger
155+
156+
**Cause**: Tag not pushed or pushed before workflow existed
157+
158+
**Solution**:
159+
```bash
160+
# Delete and re-push tag
161+
git push origin :refs/tags/v1.0.4
162+
git push origin v1.0.4
163+
```
164+
165+
### Error: Tests or build fail
166+
167+
**Cause**: Code issues preventing publish
168+
169+
**Solution**:
170+
1. Run locally first:
171+
```bash
172+
npm ci
173+
npm run build
174+
npm test
175+
npm run type-check
176+
```
177+
2. Fix issues
178+
3. Commit and re-tag
179+
## 📝 Release Workflow Configuration
180+
181+
### Key Workflow Features (`.github/workflows/release.yml`)
182+
183+
```yaml
184+
on:
185+
push:
186+
tags:
187+
- 'v*'
188+
189+
permissions:
190+
contents: write # Create GitHub releases
191+
id-token: write # OIDC authentication (REQUIRED!)
192+
```
193+
194+
**Critical Permissions**:
195+
- `id-token: write` - Required for npm Trusted Publishing (OIDC)
196+
- `contents: write` - Needed to create GitHub releases
197+
198+
**What Makes It Work**:
199+
1. **NO registry-url** in setup-node (prevents .npmrc conflicts)
200+
2. **NO NODE_AUTH_TOKEN** environment variable
201+
3. **npm >= 11.5.1** (automatically upgraded in workflow)
202+
4. **--provenance flag** in npm publish command
203+
5. **Triggered by tags** (not push to main)
204+
205+
### Workflow Steps Explained
206+
207+
```yaml
208+
- uses: actions/setup-node@v4
209+
with:
210+
node-version: '20'
211+
# NO registry-url here!
212+
213+
- name: Upgrade npm for Trusted Publishing
214+
run: npm install -g npm@latest
215+
216+
- name: Publish to npm with Provenance
217+
run: npm publish --provenance --access public
218+
# OIDC happens automatically - no tokens needed!
219+
```
220+
221+
## 🎯 Benefits Over Token-Based Publishing
222+
223+
| Feature | Token-Based | Trusted Publishing |
224+
|---------|-------------|-------------------|
225+
| **Token management** | Required | None |
226+
| **Token rotation** | Manual | Automatic |
227+
| **Token expiration** | 90 days | N/A |
228+
| **Security risk** | High (token leak) | Low (OIDC) |
229+
| **Provenance** | Optional | Included |
230+
| **Supply chain** | Not verified | Cryptographically verified |
231+
| **Transparency** | None | Public log |
232+
| **Audit trail** | Limited | Complete |
233+
234+
## 📚 Resources
235+
236+
- **npm Provenance**: https://docs.npmjs.com/generating-provenance-statements
237+
- **npm Trusted Publishing**: https://docs.npmjs.com/trusted-publishers/
238+
- **GitHub OIDC**: https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect
239+
- **Sigstore**: https://www.sigstore.dev/
240+
## 🔒 Security Best Practices
241+
242+
1. **Never commit tokens** to repository
243+
2. **Enable 2FA** on npm account
244+
3. **Review Dependabot PRs** before merging
245+
4. **Monitor security advisories** via GitHub Alerts
246+
5. **Check CodeQL results** weekly
247+
6. **Verify provenance** for published packages
248+
7. **Keep dependencies updated** (Dependabot handles this)
249+
8. **Run local tests** before tagging releases
250+
251+
## 📊 Monitoring & Badges
252+
253+
### Package Status
254+
255+
[![npm version](https://badge.fury.io/js/%40crashbytes%2Freact-version-compare.svg)](https://www.npmjs.com/package/@crashbytes/react-version-compare)
256+
[![npm Audit](https://github.com/CrashBytes/react-version-compare/actions/workflows/security-audit.yml/badge.svg)](https://github.com/CrashBytes/react-version-compare/actions/workflows/security-audit.yml)
257+
[![CodeQL](https://github.com/CrashBytes/react-version-compare/actions/workflows/security-audit.yml/badge.svg?branch=main)](https://github.com/CrashBytes/react-version-compare/security/code-scanning)
258+
[![React 18](https://github.com/CrashBytes/react-version-compare/actions/workflows/react-compat.yml/badge.svg)](https://github.com/CrashBytes/react-version-compare/actions/workflows/react-compat.yml)
259+
[![npm Provenance](https://img.shields.io/badge/provenance-sigstore-blue)](https://www.npmjs.com/package/@crashbytes/react-version-compare)
260+
261+
### Monitoring Commands
262+
263+
```bash
264+
# Watch workflow runs
265+
gh run list --limit 5
266+
267+
# View specific workflow
268+
gh run view <run-id>
269+
270+
# Check security issues
271+
gh api repos/CrashBytes/react-version-compare/vulnerability-alerts
272+
273+
# View Dependabot alerts
274+
gh api repos/CrashBytes/react-version-compare/dependabot/alerts
275+
```
276+
277+
## 🎓 Key Learnings
278+
279+
From our setup experience:
280+
281+
1. **Environment field MUST be blank** - Most common failure cause
282+
2. **Case sensitivity matters** - Organization name must be exact
283+
3. **Full repository name required** - Not abbreviated
284+
4. **Workflow filename must match** - Exactly as in `.github/workflows/`
285+
5. **npm CLI version critical** - Must be ≥ 11.5.1 for OIDC
286+
6. **NO registry-url in workflow** - Causes .npmrc conflicts
287+
288+
## ✅ Setup Checklist
289+
290+
- [x] npm Trusted Publisher configured on npmjs.com
291+
- [x] Organization: `CrashBytes` (exact case)
292+
- [x] Repository: `react-version-compare` (full name)
293+
- [x] Workflow: `release.yml` (exact filename)
294+
- [x] Environment: (blank/empty)
295+
- [x] Release workflow created (`.github/workflows/release.yml`)
296+
- [x] Security audit workflow (`.github/workflows/security-audit.yml`)
297+
- [x] React compatibility testing (`.github/workflows/react-compat.yml`)
298+
- [x] Dependabot configuration (`.github/dependabot.yml`)
299+
- [x] SECURITY.md policy document
300+
- [x] README badges updated
301+
- [x] First release tested (v1.0.4)
302+
## 🚨 Migration Notes
303+
304+
### Old Workflow (Removed)
305+
306+
The previous `.github/workflows/publish.yml` workflow:
307+
- ❌ Auto-bumped version on every push to main
308+
- ❌ Required NPM_TOKEN secret
309+
- ❌ No provenance generation
310+
- ❌ No security infrastructure
311+
312+
### New Workflow (Current)
313+
314+
The new `.github/workflows/release.yml` workflow:
315+
- ✅ Manual version control (update package.json)
316+
- ✅ Tag-based releases (you control when)
317+
- ✅ OIDC authentication (no tokens)
318+
- ✅ Automatic provenance generation
319+
- ✅ Complete security infrastructure
320+
321+
## 📞 Support
322+
323+
For issues or questions:
324+
- GitHub Issues: https://github.com/CrashBytes/react-version-compare/issues
325+
- Security: security@crashbytes.com
326+
327+
---
328+
329+
**Last Updated**: 2026-01-14
330+
**Package**: @crashbytes/react-version-compare
331+
**Current Version**: 1.0.4
332+
**Status**: ✅ Production Ready

0 commit comments

Comments
 (0)