HIP: Automated Release Process for Helm

hips/hip-9999.md

@@ -0,0 +1,246 @@
+---
+hip: 9999
+title: "Automated Release Process for Helm"
+authors: ["Scott Rigby <[email protected]>"]
+created: "2025-09-12"
+type: "process"
+status: "draft"
+---
+
+## Abstract
+
+This HIP proposes automating significant portions of the Helm release process through GitHub Actions workflows while maintaining human oversight and security. The proposal introduces pull request-based automation for version updates, release candidate generation, documentation synchronization, and cross-repository coordination between helm/helm and helm/helm-www. The automation preserves the current manual review checkpoints while eliminating error-prone repetitive tasks, reducing release cycle time, and improving consistency.
+
+## Motivation
+
+The current Helm release process, documented in the [Release Checklist](https://github.com/helm/helm-www/blob/main/content/en/docs/community/release_checklist.md), involves 11 manual steps requiring maintainers to:
+
+- Manually edit multiple files across different repositories
+- Coordinate updates between helm/helm and helm/helm-www repositories
+- Perform repetitive version string replacements in test files
+- Manually manage GitHub milestones and releases
+- Switch between multiple repository contexts during a single release
+
+This manual process introduces several problems:
+
+1. **Human Error**: Manual file editing leads to version mismatches and missed updates
+2. **Time Consumption**: Maintainers spend significant time on repetitive tasks
+3. **Context Switching**: Managing two repositories simultaneously increases cognitive load
+4. **Inconsistency**: Manual processes vary between different release managers
+5. **Bottlenecks**: Only maintainers familiar with the entire process can perform releases
+6. **Delayed Documentation**: Website updates often lag behind releases
+
+The existing process works but does not scale efficiently with Helm's release cadence and growing maintainer team.
+
+## Rationale
+
+### Design Principles
+
+1. **Human Review Preserved**: All automation presents changes as pull requests requiring maintainer approval
+2. **Security First**: No bypass of existing security measures (signed commits, GPG signatures)
+3. **Draft Mode**: Automated releases created in draft mode for final human review
+4. **Incremental Adoption**: Can be implemented and rolled out progressively
+5. **Rollback Capability**: Easy to revert to manual process if needed
+
+### Alternative Approaches Considered
+
+**Full Automation**: Rejected because it removes necessary human judgment for release timing, quality assessment, and community communication.
+
+**External Tools**: Considered tools like Release Drafter, but they lack the cross-repository coordination and Helm-specific requirements.
+
+**Monolithic Workflow**: Rejected in favor of modular workflows that can be maintained and debugged independently.
+
+## Specification
+
+### Workflow Architecture
+
+#### 1. Release Preparation Workflow (`helm/helm`)
+
+**Trigger**: Manual workflow dispatch with inputs:
+- Release type (major/minor/patch)
+- Target version (e.g., v3.20.0)
+- Release date
+
+**Actions**:
+1. Create release branch from main
+2. Update version in `internal/version/version.go`
+3. Update all test data files with new version
+4. Generate release notes template using commit history
+5. Create/update GitHub milestone
+6. Create pull request with all changes
+
+**Artifacts**: Pull request ready for maintainer review
+
+#### 2. Release Candidate Workflow (`helm/helm`)
+
+**Trigger**: Merge of release preparation PR
+
+**Actions**:
+1. Create signed, annotated git tag for RC
+2. Trigger existing CI/CD for artifact building
+3. Create draft GitHub release with RC tag
+4. Generate and attach PGP signatures (if signing key available)
+5. Post notification to configured channels
+
+**Artifacts**: Draft GitHub release with RC artifacts
+
+#### 3. Final Release Workflow (`helm/helm`)
+
+**Trigger**: Manual approval/publication of RC draft release
+
+**Actions**:
+1. Create signed, annotated final release tag
+2. Update draft release to final
+3. Trigger documentation update workflow
+4. Close milestone
+5. Generate community announcement template
+
+#### 4. Documentation Update Workflow (`helm/helm-www`)
+
+**Trigger**: Webhook from helm/helm final release publication
+
+**Actions**:
+1. Update `config.toml` with new version information
+2. Update `params.nextversion` with next planned release
+3. Update version skew documentation
+4. Update release calendar with next release dates
+5. Create pull request in helm/helm-www
+
+**Artifacts**: Pull request in helm/helm-www ready for review
+
+### File Structure
+
+```
+.github/workflows/
+├── prepare-release.yml          # Release preparation automation
+├── release-candidate.yml        # RC creation and management
+├── finalize-release.yml         # Final release publication
+└── update-documentation.yml     # Cross-repo docs updates
+
+scripts/
+├── update-version-files.sh      # Version update automation
+├── generate-release-notes.sh    # Release notes generation
+└── update-test-data.sh          # Test file version updates
+```
+
+### Configuration
+
+New configuration file `.github/release-config.yml`:
+
+```yaml
+# Release automation configuration
+version_files:
+  - path: "internal/version/version.go"
+    pattern: 'version = "v{VERSION}"'
+  - path: "cmd/helm/testdata/output/version.txt"
+    pattern: 'Version:"{VERSION}"'
+  # ... additional files
+
+repositories:
+  docs_repo: "helm/helm-www"
+
+signing:
+  gpg_key_id: "${{ secrets.GPG_KEY_ID }}"
+  gpg_private_key: "${{ secrets.GPG_PRIVATE_KEY }}"
+```
+
+### Permissions and Security
+
+Required GitHub App permissions:
+- Contents: Write (for creating branches, tags, releases)
+- Pull Requests: Write (for creating PRs)
+- Metadata: Read (for accessing repository info)
+- Actions: Write (for triggering cross-repo workflows)
+
+Required secrets:
+- `GITHUB_APP_ID`: GitHub App ID for cross-repo access
+- `GITHUB_APP_PRIVATE_KEY`: GitHub App private key
+- `GPG_PRIVATE_KEY`: PGP signing key (optional)
+
+## Backwards Compatibility
+
+This proposal introduces new automation alongside the existing manual process:
+
+1. **Graceful Rollback**: Manual process remains fully functional if automation fails
+2. **Opt-in Adoption**: Teams can choose to use automation for specific steps
+3. **No Breaking Changes**: No modifications to existing release artifacts or tags
+4. **Existing Tool Compatibility**: All existing tooling continues to work unchanged
+
+The automation enhances rather than replaces the current process, ensuring maintainers can fall back to manual steps if needed.
+
+## Security Implications
+
+### Enhanced Security
+
+1. **Consistent Process**: Automation reduces risk of human error in security-critical steps
+2. **Audit Trail**: All changes tracked through GitHub PR system
+3. **Access Control**: GitHub App permissions more restrictive than individual maintainer access
+4. **Signed Commits**: Automation maintains commit signing requirements
+
+### Security Considerations
+
+1. **Secret Management**: GPG keys and tokens stored in GitHub Secrets
+2. **Cross-Repo Access**: GitHub App tokens limited to minimum required permissions
+3. **Draft Mode**: All releases created in draft mode, requiring manual publication
+4. **Approval Gates**: All changes require PR approval before implementation
+
+## How to Teach This
+
+### Maintainer Documentation
+
+1. Update existing release checklist with automation options
+2. Create troubleshooting guide for automation failures
+3. Document rollback procedures
+4. Provide workflow customization examples
+
+### Training Materials
+
+1. Video walkthrough of automated release process
+2. Comparison guide: manual vs. automated steps
+3. Emergency procedures documentation
+4. FAQ for common automation issues
+
+## Reference Implementation
+
+Initial implementation should focus on the release preparation workflow as it provides the highest value with lowest risk:
+
+1. **Phase 1**: Release preparation automation (version updates, PR creation)
+2. **Phase 2**: Release candidate automation
+3. **Phase 3**: Documentation update automation
+4. **Phase 4**: Full workflow integration and community notification
+
+Each phase can be tested in isolation and rolled back if issues arise.
+
+## Rejected Ideas
+
+### Fully Automated Releases
+
+Rejected because release timing requires human judgment based on:
+- Community feedback on release candidates
+- Critical bug discovery during testing
+- External factors (holidays, conferences, security issues)
+
+### Slack/Discord Bot Interface
+
+While potentially useful, adds complexity and another system to maintain. GitHub's existing interfaces provide sufficient control.
+
+### Automatic Backporting
+
+Patch release cherry-picking requires human judgment for:
+- Risk assessment of changes
+- Conflict resolution
+- Testing scope determination
+
+## Open Issues
+
+1. **GPG Key Management**: Best practices for storing and rotating signing keys in CI
+2. **Cross-Org Coordination**: Technical approach for coordinating releases with other CNCF projects
+3. **Rollback Testing**: Comprehensive testing scenarios for automation failures
+4. **Metrics Collection**: Tracking automation success rates and time savings
+
+## References
+
+1. [Current Release Checklist](https://github.com/helm/helm-www/blob/main/content/en/docs/community/release_checklist.md)
+2. [GitHub Actions Documentation](https://docs.github.com/en/actions)
+3. [Semantic Versioning](https://semver.org/)
+4. [GitHub Apps Documentation](https://docs.github.com/en/developers/apps)