headlamp-sealed-secrets-plugin/RELEASE_GUIDE.md

Release Guide

This guide provides step-by-step instructions for releasing a new version of the Headlamp Sealed Secrets plugin.

Prerequisites

• Ensure you're on the main branch with all changes committed
• All new features are documented and tested
• CHANGELOG.md is updated with release notes

Quick Release (5 minutes)

For Patch Releases (e.g., 0.2.4 → 0.2.5)

# 1. Enter plugin directory
cd headlamp-sealed-secrets

# 2. Bump patch version (updates package.json)
npm version patch

# 3. Return to repo root
cd ..

# 4. Update artifacthub-pkg.yml with new version
# Edit the file manually:
# - Change version: 0.2.5
# - Change appVersion: 0.2.5
# OR use sed:
sed -i '' 's/version: 0.2.4/version: 0.2.5/' artifacthub-pkg.yml
sed -i '' 's/appVersion: 0.2.4/appVersion: 0.2.5/' artifacthub-pkg.yml

# 5. Update CHANGELOG.md with release date
# Edit manually or ensure version section exists with today's date

# 6. Commit version bump
git add headlamp-sealed-secrets/package.json artifacthub-pkg.yml CHANGELOG.md
git commit -m "chore(release): bump version to 0.2.5"

# 7. Push to main
git push origin main

# 8. Create and push tag (triggers publish workflow)
git tag -a v0.2.5 -m "Release version 0.2.5"
git push origin v0.2.5

# 9. Monitor GitHub Actions
# Visit: https://github.com/privilegedescalation/headlamp-sealed-secrets-plugin/actions

Detailed Release Process

Step 1: Prepare Release Branch

# Ensure on main with latest changes
git checkout main
git pull origin main

# Verify no uncommitted changes
git status

# Optional: Create feature branch for release prep (for discussion)
git checkout -b release/v0.2.5

Step 2: Verify Quality

# Build and test locally
cd headlamp-sealed-secrets

# Install dependencies
npm ci

# Type check
npm run tsc

# Lint
npm run lint

# Build
npm run build

# Test locally (if applicable)
npm test

cd ..

Step 3: Update Version

Option A: Automated (Recommended)

cd headlamp-sealed-secrets

# Use npm version to update package.json
# This automatically updates version in package.json
npm version patch    # For patch releases (0.2.4 → 0.2.5)
npm version minor    # For minor releases (0.2.4 → 0.3.0)
npm version major    # For major releases (0.2.4 → 1.0.0)

cd ..

# Verify it was updated
grep '"version"' headlamp-sealed-secrets/package.json

Option B: Manual

Edit headlamp-sealed-secrets/package.json:

{
  "version": "0.2.5",
  ...
}

Step 4: Update Artifact Hub Metadata

Edit artifacthub-pkg.yml in repository root:

version: 0.2.5              # Must match package.json
appVersion: 0.2.5           # Must match package.json
createdAt: "2026-02-12T00:00:00Z"

annotations:
  headlamp/plugin/archive-url: "https://github.com/privilegedescalation/headlamp-sealed-secrets-plugin/releases/download/v0.2.5/headlamp-sealed-secrets-0.2.5.tar.gz"
  headlamp/plugin/archive-checksum: "SHA256:..."  # Will be auto-updated by workflow

Note: The archive-checksum will be auto-calculated by the publish workflow, so you can leave it as-is or set a placeholder.

Step 5: Update CHANGELOG

Edit CHANGELOG.md:

# Changelog

## Unreleased

...future changes...

## [0.2.5] - 2026-02-12

### Added
- New feature description

### Fixed
- Bug fix description

### Changed
- Changed behavior description

## [0.2.4] - 2026-02-11

...previous releases...

Format guidelines:

• Date in ISO format: YYYY-MM-DD
• Sections: Added, Fixed, Changed, Deprecated, Removed, Security
• Link to version tag at bottom

Step 6: Commit Release Changes

# Stage version and changelog updates
git add headlamp-sealed-secrets/package.json artifacthub-pkg.yml CHANGELOG.md

# Verify changes
git diff --cached

# Commit with conventional message
git commit -m "chore(release): bump version to 0.2.5"

Step 7: Push to Main

# Push commit to main
git push origin main

# Verify on GitHub
# https://github.com/privilegedescalation/headlamp-sealed-secrets-plugin/commits/main

Step 8: Create Release Tag

# Create annotated tag (not lightweight)
git tag -a v0.2.5 -m "Release version 0.2.5"

# Verify tag
git tag -l -n v0.2.5

# Push tag to remote (triggers publish workflow)
git push origin v0.2.5

# Verify it was pushed
git ls-remote origin | grep tags | tail -5

Step 9: Monitor Publish Workflow

# Watch workflow execution
# GitHub URL: https://github.com/privilegedescalation/headlamp-sealed-secrets-plugin/actions

# Expected steps (3-5 minutes):
# 1. ✓ Build and lint
# 2. ✓ Create tarball
# 3. ✓ Upload to GitHub release
# 4. ✓ Update artifacthub-pkg.yml with checksum
# 5. ✓ Push metadata update to main

Step 10: Verify Release

GitHub Release

# Check GitHub releases page
# https://github.com/privilegedescalation/headlamp-sealed-secrets-plugin/releases

# Verify:
# - Release tag v0.2.5 exists
# - Release description (auto-generated from commits)
# - Tarball artifact: headlamp-sealed-secrets-0.2.5.tar.gz
# - Size looks reasonable (~90-100 KB)

Artifact Hub

# Wait 5-10 minutes for sync
# Visit: https://artifacthub.io/packages/headlamp-sealed-secrets

# Verify:
# - Version 0.2.5 appears
# - Archive URL points to GitHub release
# - Checksum matches GitHub release
# - Description and metadata display correctly

Direct Download

# Verify tarball integrity
ARCHIVE="headlamp-sealed-secrets-0.2.5.tar.gz"
DOWNLOAD_URL="https://github.com/privilegedescalation/headlamp-sealed-secrets-plugin/releases/download/v0.2.5/${ARCHIVE}"

# Download and verify
wget "${DOWNLOAD_URL}"
sha256sum "${ARCHIVE}"

# Compare with artifacthub-pkg.yml checksum
grep archive-checksum artifacthub-pkg.yml

Version Numbering

Follow Semantic Versioning (SemVer):

MAJOR.MINOR.PATCH

0.2.5
├── 0 = Major version (breaking changes)
├── 2 = Minor version (new features, backward compatible)
└── 5 = Patch version (bug fixes)

When to bump each number:

• Patch (0.2.4 → 0.2.5): Bug fixes, security patches

  • Command: npm version patch
  • Example: Fix dialog close button, improve error handling

• Minor (0.2.0 → 0.3.0): New features (backward compatible)

  • Command: npm version minor
  • Example: Add certificate expiry warnings

• Major (0.x.x → 1.0.0): Breaking changes, significant redesign

  • Command: npm version major
  • Example: Change UI structure, new required permissions

Pre-Release Versions (Optional)

For pre-release testing:

cd headlamp-sealed-secrets
npm version preminor --preid=rc  # Results in 0.3.0-rc.0
cd ..

git tag -a v0.3.0-rc.0 -m "Release candidate 0.3.0-rc.0"
git push origin v0.3.0-rc.0

Note: Artifact Hub will skip pre-release versions by default.

Release Checklist

Before releasing:

General Checklist:
- [ ] All tests passing (CI workflow)
- [ ] Code reviewed and merged to main
- [ ] No uncommitted changes in working directory
- [ ] CHANGELOG.md updated with release notes

Version Updates:
- [ ] headlamp-sealed-secrets/package.json version updated
- [ ] artifacthub-pkg.yml version matches package.json
- [ ] CHANGELOG.md has version heading with date

Git Steps:
- [ ] Changes committed to main
- [ ] Changes pushed to origin/main
- [ ] Tag created with format v0.2.5
- [ ] Tag pushed to origin

Verification:
- [ ] Publish workflow completes successfully
- [ ] GitHub release created with tarball
- [ ] Artifact Hub synced within 10 minutes
- [ ] Archive URL accessible
- [ ] Checksum matches

Post-Release:
- [ ] Close related issues/PRs
- [ ] Announce release if applicable
- [ ] Monitor for bug reports

Troubleshooting

"Tag already exists"

# If you made a mistake with tag name:
git tag -d v0.2.5              # Delete local tag
git push origin -d v0.2.5      # Delete remote tag
git tag -a v0.2.5 -m "..."    # Create correct tag
git push origin v0.2.5

"Publish workflow failed"

1. Check workflow logs: GitHub Actions → workflow run
2. Common issues:
   • Missing dependencies: Run npm ci in headlamp-sealed-secrets/
   • Build errors: Run npm run build locally to reproduce
   • Type errors: Run npm run tsc locally
3. Fix and retry:

   git tag -d v0.2.5
   git push origin -d v0.2.5
   # Fix the issue
   git push origin main
   git tag -a v0.2.5 -m "..."
   git push origin v0.2.5
   

"Artifact Hub still shows old version"

# Option 1: Wait 10 minutes for auto-sync
# Option 2: Force sync from Artifact Hub UI:
# - Login to artifacthub.io
# - Go to control-panel/repositories
# - Find this repository
# - Click "Trigger sync"

# Option 3: Verify metadata is correct
grep "version:" artifacthub-pkg.yml
grep "archive-url:" artifacthub-pkg.yml
grep "archive-checksum:" artifacthub-pkg.yml

"Checksum mismatch"

Problem: Local checksum doesn't match Artifact Hub

Solution: Never rebuild locally - always use the released tarball from GitHub

# WRONG (don't do this):
npm run build
npm pack
sha256sum headlamp-sealed-secrets-0.2.5.tar.gz

# RIGHT (use released tarball):
wget https://github.com/.../releases/download/v0.2.5/headlamp-sealed-secrets-0.2.5.tar.gz
sha256sum headlamp-sealed-secrets-0.2.5.tar.gz

Automation & Cleanup

Auto-Cleanup Old Version Directories (Optional)

The /headlamp-sealed-secrets-plugin/0.2.X/ directories are historical artifacts and no longer needed. They were used before automated releases:

# Optional: Archive for historical reference
tar -czf releases-archive.tar.gz headlamp-sealed-secrets-plugin/

# Delete the directory
rm -rf headlamp-sealed-secrets-plugin/

# Commit cleanup
git add -u
git commit -m "chore: remove legacy version directories (GitHub releases are now source of truth)"
git push origin main

NPM Publishing (Optional)

If you want to also publish to NPM (note: Headlamp doesn't support NPM plugin downloads):

1. Create NPM token: https://www.npmjs.com/settings/your-username/tokens
2. Add to GitHub secret: NPM_TOKEN
3. Uncomment in publish workflow (optional step)

For Headlamp plugins, GitHub releases are the standard distribution method.

Support

• Headlamp Plugin Docs: https://headlamp.dev/docs/latest/development/plugins/publishing/
• Artifact Hub Docs: https://artifacthub.io/docs
• Repository: https://github.com/privilegedescalation/headlamp-sealed-secrets-plugin
• Issues: https://github.com/privilegedescalation/headlamp-sealed-secrets-plugin/issues