Add publishing documentation and guides
This commit is contained in:
+161
@@ -0,0 +1,161 @@
|
||||
# Quick Start Guide - Publishing to Artifact Hub & NPM
|
||||
|
||||
## 🚀 Fast Track (5 Steps)
|
||||
|
||||
### 1. Create GitHub Repository
|
||||
|
||||
```bash
|
||||
# On GitHub, create: cpfarhood/headlamp-sealed-secrets-plugin
|
||||
# Then run:
|
||||
|
||||
git remote add origin https://github.com/cpfarhood/headlamp-sealed-secrets-plugin.git
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
### 2. Configure NPM Token for GitHub Actions
|
||||
|
||||
1. Go to https://www.npmjs.com/settings/cpfarhood/tokens
|
||||
2. Create new **Automation** token
|
||||
3. Copy the token
|
||||
4. Go to https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/settings/secrets/actions
|
||||
5. Create secret: `NPM_TOKEN` = your token
|
||||
|
||||
### 3. Tag and Release
|
||||
|
||||
```bash
|
||||
# Create version tag
|
||||
git tag -a v0.1.0 -m "Release version 0.1.0"
|
||||
git push origin v0.1.0
|
||||
```
|
||||
|
||||
### 4. Verify Automated Publishing
|
||||
|
||||
The GitHub Action will automatically:
|
||||
- ✅ Build the plugin
|
||||
- ✅ Run tests
|
||||
- ✅ Publish to NPM
|
||||
- ✅ Create GitHub Release
|
||||
|
||||
Check progress at: https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/actions
|
||||
|
||||
### 5. Verify Artifact Hub Sync
|
||||
|
||||
**Artifact Hub is already configured!**
|
||||
- Repository ID: `5574d37c-c4ae-45ab-a378-ef24aaba5b4c`
|
||||
- Points to: `main` branch
|
||||
- Auto-syncs every few hours
|
||||
|
||||
To verify after ~30 minutes:
|
||||
1. Go to https://artifacthub.io/control-panel/repositories
|
||||
2. Find your repository
|
||||
3. Check last sync status
|
||||
|
||||
## 📦 What's Included
|
||||
|
||||
All files are ready:
|
||||
- ✅ `package.json` - NPM metadata
|
||||
- ✅ `artifacthub-pkg.yml` - Artifact Hub metadata
|
||||
- ✅ `artifacthub-repo.yml` - Repository config
|
||||
- ✅ `.github/workflows/publish.yml` - Auto-publish on tag
|
||||
- ✅ `.github/workflows/ci.yml` - CI on push/PR
|
||||
- ✅ `LICENSE` - Apache 2.0
|
||||
- ✅ `README.md` - Full documentation
|
||||
- ✅ Built plugin in `dist/` (339KB)
|
||||
|
||||
## 🔍 Verify After Publishing
|
||||
|
||||
### NPM (within minutes)
|
||||
```bash
|
||||
npm view headlamp-sealed-secrets
|
||||
# or visit: https://www.npmjs.com/package/headlamp-sealed-secrets
|
||||
```
|
||||
|
||||
### GitHub Release (within minutes)
|
||||
https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/releases
|
||||
|
||||
### Artifact Hub (within hours)
|
||||
https://artifacthub.io/packages/headlamp/headlamp-sealed-secrets
|
||||
|
||||
## 🛠 Manual Publish (Alternative)
|
||||
|
||||
If you prefer to publish manually:
|
||||
|
||||
```bash
|
||||
cd headlamp-sealed-secrets
|
||||
|
||||
# Login to NPM (first time only)
|
||||
npm login
|
||||
|
||||
# Publish
|
||||
npm publish --access public
|
||||
```
|
||||
|
||||
## 📋 Pre-Publish Checklist
|
||||
|
||||
Before running step 1:
|
||||
- [x] Code is complete and tested
|
||||
- [x] `npm run build` succeeds
|
||||
- [x] `npm run tsc` passes
|
||||
- [x] `npm run lint` passes
|
||||
- [x] README.md is complete
|
||||
- [x] LICENSE file exists
|
||||
- [x] Artifact Hub metadata is correct
|
||||
- [x] GitHub Actions workflows configured
|
||||
|
||||
## 🎯 Success Criteria
|
||||
|
||||
Your plugin is successfully published when:
|
||||
1. ✅ NPM package is live: `npm install -g headlamp-sealed-secrets`
|
||||
2. ✅ GitHub Release exists with artifacts
|
||||
3. ✅ Artifact Hub shows the package (may take 24h for initial sync)
|
||||
4. ✅ Installation instructions work
|
||||
|
||||
## 🔄 Future Updates
|
||||
|
||||
For version 0.1.1, 0.2.0, etc.:
|
||||
|
||||
```bash
|
||||
# Update version
|
||||
cd headlamp-sealed-secrets
|
||||
npm version patch # or minor/major
|
||||
|
||||
# Update artifacthub-pkg.yml to match
|
||||
# Edit version: 0.1.1
|
||||
|
||||
# Commit, tag, push
|
||||
cd ..
|
||||
git add .
|
||||
git commit -m "Release v0.1.1"
|
||||
git tag -a v0.1.1 -m "Release version 0.1.1"
|
||||
git push origin main
|
||||
git push origin v0.1.1
|
||||
```
|
||||
|
||||
## 📚 Full Documentation
|
||||
|
||||
For detailed instructions, see:
|
||||
- **PUBLISHING.md** - Complete publishing guide
|
||||
- **README.md** - User documentation
|
||||
- **IMPLEMENTATION_SUMMARY.md** - Technical details
|
||||
|
||||
## ⚡ TL;DR - One Command
|
||||
|
||||
After setting up GitHub repo and NPM token:
|
||||
|
||||
```bash
|
||||
git remote add origin https://github.com/cpfarhood/headlamp-sealed-secrets-plugin.git
|
||||
git push -u origin main
|
||||
git tag -a v0.1.0 -m "Release version 0.1.0" && git push origin v0.1.0
|
||||
```
|
||||
|
||||
Then wait for GitHub Actions to complete! 🎉
|
||||
|
||||
---
|
||||
|
||||
**Current Status:**
|
||||
- ✅ Code committed to `main` branch
|
||||
- 🔲 Pushed to GitHub
|
||||
- 🔲 NPM token configured
|
||||
- 🔲 Version tagged
|
||||
- 🔲 Published to NPM
|
||||
- 🔲 Listed on Artifact Hub
|
||||
@@ -0,0 +1,205 @@
|
||||
# ✅ Ready to Publish - Headlamp Sealed Secrets Plugin
|
||||
|
||||
## Current Status: **READY FOR PUBLICATION** 🚀
|
||||
|
||||
All code is complete, tested, and committed to the `main` branch.
|
||||
|
||||
---
|
||||
|
||||
## 📊 Summary
|
||||
|
||||
| Item | Status | Details |
|
||||
|------|--------|---------|
|
||||
| **Plugin Code** | ✅ Complete | ~1,345 lines of TypeScript/React |
|
||||
| **Build** | ✅ Success | 339.42 kB (93.21 kB gzipped) |
|
||||
| **Type Check** | ✅ Pass | Zero TypeScript errors |
|
||||
| **Linting** | ✅ Pass | No lint errors |
|
||||
| **Documentation** | ✅ Complete | README, PUBLISHING guide, CHANGELOG |
|
||||
| **License** | ✅ Apache 2.0 | Full license file included |
|
||||
| **Artifact Hub** | ✅ Configured | ID: 5574d37c-c4ae-45ab-a378-ef24aaba5b4c |
|
||||
| **CI/CD** | ✅ Ready | GitHub Actions workflows configured |
|
||||
| **Git Commit** | ✅ Done | Committed to `main` branch |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Next Steps (3 Actions Required)
|
||||
|
||||
### 1. Create GitHub Repository
|
||||
```bash
|
||||
# On GitHub: Create repository "headlamp-sealed-secrets-plugin" under cpfarhood
|
||||
# Then run:
|
||||
git remote add origin https://github.com/cpfarhood/headlamp-sealed-secrets-plugin.git
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
### 2. Configure NPM Token
|
||||
- Create NPM automation token: https://www.npmjs.com/settings/cpfarhood/tokens
|
||||
- Add to GitHub secrets: https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/settings/secrets/actions
|
||||
- Secret name: `NPM_TOKEN`
|
||||
|
||||
### 3. Create Release Tag
|
||||
```bash
|
||||
git tag -a v0.1.0 -m "Release version 0.1.0"
|
||||
git push origin v0.1.0
|
||||
```
|
||||
|
||||
**GitHub Actions will automatically publish to NPM and create a release!**
|
||||
|
||||
---
|
||||
|
||||
## 📦 What Gets Published
|
||||
|
||||
### NPM Package
|
||||
- Package name: `headlamp-sealed-secrets`
|
||||
- Files included:
|
||||
- `dist/main.js` (built plugin)
|
||||
- `README.md`
|
||||
- `LICENSE`
|
||||
- `package.json`
|
||||
|
||||
### GitHub Release
|
||||
- Tag: `v0.1.0`
|
||||
- Artifacts:
|
||||
- Built plugin
|
||||
- Source code (auto)
|
||||
- Release notes (auto-generated)
|
||||
|
||||
### Artifact Hub
|
||||
- Auto-syncs from GitHub `main` branch
|
||||
- Metadata from `artifacthub-pkg.yml`
|
||||
- Usually visible within 24 hours
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Verification
|
||||
|
||||
After publishing, verify:
|
||||
|
||||
### NPM (5-10 minutes)
|
||||
```bash
|
||||
npm view headlamp-sealed-secrets
|
||||
npm install -g headlamp-sealed-secrets
|
||||
```
|
||||
|
||||
### GitHub (immediate)
|
||||
- Check Actions: https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/actions
|
||||
- View Release: https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/releases
|
||||
|
||||
### Artifact Hub (up to 24 hours)
|
||||
- Control Panel: https://artifacthub.io/control-panel/repositories
|
||||
- Package Page: https://artifacthub.io/packages/headlamp/headlamp-sealed-secrets
|
||||
|
||||
---
|
||||
|
||||
## 📁 Repository Structure
|
||||
|
||||
```
|
||||
headlamp-sealed-secrets-plugin/
|
||||
├── .github/workflows/ # CI/CD automation
|
||||
│ ├── ci.yml # Tests on every push
|
||||
│ └── publish.yml # Auto-publish on tags
|
||||
├── headlamp-sealed-secrets/ # Plugin source
|
||||
│ ├── dist/ # Built plugin (339KB)
|
||||
│ ├── src/ # TypeScript source
|
||||
│ ├── package.json # NPM metadata
|
||||
│ ├── artifacthub-pkg.yml # Artifact Hub metadata
|
||||
│ ├── README.md # User documentation
|
||||
│ └── LICENSE # Apache 2.0
|
||||
├── artifacthub-repo.yml # Repository config
|
||||
├── CHANGELOG.md # Version history
|
||||
├── PUBLISHING.md # Detailed publish guide
|
||||
├── QUICK_START.md # Fast track guide
|
||||
└── README.md # (to be created)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎉 Features Delivered
|
||||
|
||||
✅ **Core Functionality**
|
||||
- SealedSecret CRD integration
|
||||
- List and detail views
|
||||
- Client-side encryption
|
||||
- Decryption support
|
||||
- Sealing keys management
|
||||
- Settings configuration
|
||||
|
||||
✅ **Security**
|
||||
- Browser-only encryption
|
||||
- RSA-OAEP + AES-256-GCM
|
||||
- kubeseal-compatible
|
||||
- RBAC-aware
|
||||
- Auto-hide sensitive data
|
||||
|
||||
✅ **Integration**
|
||||
- Headlamp sidebar navigation
|
||||
- Secret detail view integration
|
||||
- Deep linking support
|
||||
- Error handling
|
||||
- Graceful degradation
|
||||
|
||||
✅ **Developer Experience**
|
||||
- Full TypeScript
|
||||
- Comprehensive documentation
|
||||
- CI/CD automation
|
||||
- Easy installation
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation Files
|
||||
|
||||
All documentation is complete:
|
||||
|
||||
- **README.md** (plugin dir) - User guide with installation, usage, troubleshooting
|
||||
- **PUBLISHING.md** - Step-by-step publishing instructions
|
||||
- **QUICK_START.md** - Fast track to publish
|
||||
- **CHANGELOG.md** - Version history
|
||||
- **IMPLEMENTATION_SUMMARY.md** - Technical details
|
||||
- **LICENSE** - Apache 2.0 license text
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Important Notes
|
||||
|
||||
1. **NPM Token**: Keep it secret! Never commit to git
|
||||
2. **First Publish**: Use `npm publish --access public` if manual
|
||||
3. **Artifact Hub**: Initial sync can take 24 hours
|
||||
4. **Version Tags**: Must match package.json version
|
||||
5. **Breaking Changes**: Bump major version (0.x → 1.0)
|
||||
|
||||
---
|
||||
|
||||
## 💡 Quick Reference Commands
|
||||
|
||||
```bash
|
||||
# Build and test
|
||||
cd headlamp-sealed-secrets
|
||||
npm run build
|
||||
npm run tsc
|
||||
npm run lint
|
||||
|
||||
# Manual publish (alternative to GitHub Actions)
|
||||
npm login
|
||||
npm publish --access public
|
||||
|
||||
# Create new version
|
||||
npm version patch # 0.1.0 → 0.1.1
|
||||
npm version minor # 0.1.0 → 0.2.0
|
||||
npm version major # 0.1.0 → 1.0.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Support
|
||||
|
||||
If something goes wrong:
|
||||
- GitHub Issues: https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/issues
|
||||
- NPM Docs: https://docs.npmjs.com/
|
||||
- Artifact Hub Docs: https://artifacthub.io/docs
|
||||
- Headlamp Docs: https://headlamp.dev/docs/latest/development/plugins/
|
||||
|
||||
---
|
||||
|
||||
**Ready to publish!** Follow the 3 steps in "Next Steps" above. 🎉
|
||||
|
||||
**Questions?** Check PUBLISHING.md for detailed instructions.
|
||||
Reference in New Issue
Block a user