privilegedescalation/headlamp-sealed-secrets-plugin
12
0
Fork 0
Code Issues 2 Pull Requests 2 Actions Packages Projects Releases 27 Wiki Activity
Files
604fe06f9cc7949a415b265e80f9cbe07fd6b646
headlamp-sealed-secrets-plugin/GIT_WORKFLOW.md
T
Chris Farhood 78f5074818 chore: optimize Git workflow and CI/CD for Headlamp plugin releases 
Implements comprehensive workflow redesign addressing:
- Non-deterministic builds → Fixed with consistent Node version and npm ci
- Manual checksum management → Automated in publish workflow
- Multiple artifact locations → Single source of truth (GitHub releases)
- Individual file releases → Single tarball artifact
- Artifact Hub mismatches → No rebuild risk, use released tarball

Key improvements:
- CI workflow: faster builds with npm cache, artifact verification
- Publish workflow: deterministic builds, automatic checksum calculation,
  auto-commit of metadata updates, single tarball release
- Branch protection: require PR review and passing CI before merge
- Release process: simplified from manual to 5-minute automated workflow

Documentation:
- GIT_WORKFLOW.md: branching strategy, commit conventions, release process
- RELEASE_GUIDE.md: detailed step-by-step release instructions
- RELEASE_QUICK_REFERENCE.md: copy-paste commands for quick releases
- CI_CD_DESIGN.md: technical architecture and design decisions
- GITHUB_SETUP_CHECKLIST.md: repository configuration guide
- WORKFLOW_OPTIMIZATION_SUMMARY.md: executive summary of changes

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-12 13:43:39 -05:00

10 KiB
Raw Blame History

Git Workflow & Release Management

This document defines the recommended Git workflow and release process for the Headlamp Sealed Secrets plugin.

Overview

The workflow implements a simplified Git Flow strategy optimized for Headlamp plugins:

  • Development: All active development on main branch
  • Releases: Tagged on main, published from tags
  • Hotfixes: Emergency fixes committed to main with patch version bumps
  • Feature Branches: Optional for large features (cleanup after merge)

Branching Strategy

Main Branch (main)

  • Single integration branch for all development
  • Protected: requires PR review before merge
  • All commits must pass CI checks
  • Always releasable

Feature/Fix Branches (Optional)

  • Naming: feature/description, fix/description, docs/description, chore/description
  • Created from: main
  • Merged back to: main via PR
  • Deleted after: merge to main

Release Tags

  • Format: v<MAJOR>.<MINOR>.<PATCH> (semantic versioning)
  • Created from: main branch (latest commit)
  • Example: v0.2.4, v0.3.0
  • Never force-push or delete release tags

Commit Convention

Format

<type>(<scope>): <subject>

<body>

<footer>

Type

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation
  • style: Code style (formatting, semicolons)
  • refactor: Code refactor (no feature/fix)
  • perf: Performance improvement
  • test: Test additions/changes
  • chore: Build, dependencies, CI/CD
  • ci: CI/CD workflow changes

Scope (optional)

  • crypto: Encryption/decryption functions
  • ui: UI components
  • api: Kubernetes API calls
  • rbac: Permission checking
  • types: TypeScript types
  • artifacthub: Release artifacts
  • etc.

Subject

  • Imperative mood ("add" not "added")
  • No period at end
  • Maximum 50 characters

Examples

feat(crypto): add certificate expiry detection
fix(ui): resolve dialog form submission error
docs: update installation instructions
chore(ci): optimize build cache

Versioning

Semantic Versioning (SemVer)

  • MAJOR.MINOR.PATCH
  • MAJOR: Breaking changes to UI or API
  • MINOR: New features (backward compatible)
  • PATCH: Bug fixes

Version Files

Update these three files for each release:

  1. headlamp-sealed-secrets/package.json

    "version": "0.2.4"

  2. artifacthub-pkg.yml (root)

    version: 0.2.4
appVersion: 0.2.4

  3. CHANGELOG.md

    • Add entry under ## Unreleased → move to version heading
    • Format: Markdown with ### Added, ### Fixed, ### Changed, etc.

Release Process

Step 1: Prepare Release

# Ensure on main and up-to-date
git checkout main
git pull origin main

# Verify no uncommitted changes
git status

# Build and test locally
cd headlamp-sealed-secrets
npm run tsc
npm run lint
npm run build

# Package to verify tarball
npm run package
# Verify package size and contents
tar -tzf headlamp-sealed-secrets-*.tar.gz | head -20

# Cleanup
rm headlamp-sealed-secrets-*.tar.gz
cd ..

Step 2: Update Version Files

# Update package.json version
cd headlamp-sealed-secrets
npm version patch  # or minor, or major
cd ..

# Update artifacthub-pkg.yml (root only)
# Change version and appVersion to match package.json

# Update CHANGELOG.md
# Move unreleased items under new version heading
# Add release date in ISO format

Step 3: Commit Version Bump

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

# Push to main
git push origin main

Step 4: Create and Push Tag

# Create annotated tag with message
git tag -a v0.2.5 -m "Release version 0.2.5"

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

Step 5: Verify Release

  1. GitHub Actions: Check .github/workflows/publish.yml

    • Workflow runs automatically on tag push
    • Builds plugin and creates GitHub release
    • Logs available in Actions tab

  2. GitHub Release: https://github.com/privilegedescalation/headlamp-sealed-secrets-plugin/releases

    • Should see new release with tarball
    • Release notes auto-generated from commits
    • Verify tarball filename and checksum

  3. Artifact Hub: https://artifacthub.io/packages/headlamp-sealed-secrets

    • Syncs automatically (may take 5-10 minutes)
    • Verify version appears with correct metadata
    • Check archive URL and checksum match

CI/CD Workflows

CI Workflow (.github/workflows/ci.yml)

Trigger: Push to main and PR to main

Jobs:

  1. Lint and typecheck
  2. Build plugin
  3. Upload build artifact (for PRs)

Duration: ~2 minutes

Publish Workflow (.github/workflows/publish.yml)

Trigger: Push of version tag (e.g., v0.2.4)

Jobs:

  1. Lint and typecheck
  2. Build plugin
  3. Create tarball (deterministic)
  4. Upload tarball to GitHub release
  5. Update artifacthub-pkg.yml with checksum (NEW)
  6. Auto-calculate checksum (NEW)
  7. Commit checksum update (NEW)

Notes:

  • Deterministic builds (reproducible checksums)
  • Single artifact: tarball only
  • Automatic checksum management

Duration: ~3 minutes

Repository Structure

headlamp-sealed-secrets-plugin/
├── .github/
│   └── workflows/
│       ├── ci.yml                    # Lint, build, test on main/PR
│       └── publish.yml               # Build and publish on tag
├── headlamp-sealed-secrets/          # Plugin source code
│   ├── src/
│   ├── package.json                  # Version source of truth
│   ├── artifacthub-pkg.yml           # (DEPRECATED - see root)
│   └── dist/                         # Built plugin (gitignored)
├── artifacthub-pkg.yml               # SINGLE source of truth for releases
├── artifacthub-repo.yml              # Repository metadata
├── CHANGELOG.md                      # Release notes
├── PUBLISHING.md                     # Publishing guide (legacy)
└── GIT_WORKFLOW.md                   # This file

Cleanup Tasks

Optional: Remove Redundant Version Directories

The /headlamp-sealed-secrets-plugin/0.2.X/ directories are no longer needed with automated releases:

# These can be safely removed - GitHub releases are the source of truth
rm -rf headlamp-sealed-secrets-plugin/

Or keep for historical reference, but they won't be used for future releases.

Clean Up Artifacts During Release

The publish workflow should only generate one artifact:

  • headlamp-sealed-secrets-<VERSION>.tar.gz

Not:

  • Individual main.js files
  • Duplicated package.json files

Best Practices

  1. Build Once, Use Everywhere

    • Single build in publish workflow
    • Calculate checksum from that build
    • Use same tarball for GitHub release and Artifact Hub

  2. Deterministic Builds

    • No non-deterministic timestamps
    • No random ID generation
    • Use .npmrc for fixed dependency versions

  3. Automatic Checksums

    • Calculate checksum in publish workflow
    • Update artifacthub-pkg.yml programmatically
    • Never manually edit checksums

  4. Protected Main Branch

    • Require PR reviews
    • Require CI checks pass
    • Dismiss stale reviews on push

  5. Clean History

    • Squash merge feature branches (optional)
    • Keep linear history for releases
    • Use conventional commits

  6. Release Tags

    • Annotated tags (not lightweight)
    • Descriptive messages
    • Never delete or force-push

GitHub Setup Checklist

  • Repository created at github.com/privilegedescalation/headlamp-sealed-secrets-plugin
  • Default branch set to main
  • Branch protection enabled for main:
    • Require PR review (1+ approved)
    • Require status checks pass (CI workflow)
    • Dismiss stale reviews on push
    • Require branches up to date before merge
  • Actions enabled with local-ubuntu-latest runner
  • Secrets configured:
    • NPM_TOKEN (if publishing to NPM, optional for Headlamp)
  • Artifact Hub repository synced (ID: 5574d37c-c4ae-45ab-a378-ef24aaba5b4c)

Troubleshooting

Build Checksums Don't Match

Problem: Checksum in artifacthub-pkg.yml differs from released tarball

Cause: Rebuilding locally instead of using released artifact

Solution: Use released tarball from GitHub, never rebuild for Artifact Hub

Artifact Hub Shows Wrong Checksum

Problem: Artifact Hub metadata out of sync with release

Cause: Manual checksum edits or stale cache

Solution:

  1. Verify checksum was updated automatically in publish workflow
  2. Force Artifact Hub sync: control-panel → repositories → sync
  3. Wait 5-10 minutes for sync completion

Non-Deterministic Builds

Problem: Running npm run build twice produces different checksums

Cause: Timestamps, random IDs, or dependency variations

Solution:

  1. Ensure Node version consistent (defined in .nvmrc or actions)
  2. Use npm ci instead of npm install
  3. Lock npm version in workflows
  4. Avoid any dynamic content in builds

Tag Naming Issues

Problem: Workflow doesn't trigger on tag push

Cause: Tag format doesn't match v* pattern

Solution: Ensure tags are exactly v0.2.4 format (no extra characters)

Related Files

Resources

Reference in New Issue View Git Blame Copy Permalink