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