Claude/deep code a 011 cu swhi y gr67hky d zn fs lp#20
Merged
Conversation
…NuGet Trusted Publishing
This commit completely restructures the CI/CD pipeline to provide a cleaner,
more maintainable workflow with proper separation of concerns.
## New Workflow Architecture
### 1. Build and Test (build-and-test.yml)
- Triggers on every commit to any branch
- Multi-framework matrix: .NET 6.0, 7.0, 8.0, 9.0, .NET Standard 2.0
- Multi-OS testing: Ubuntu, Windows, macOS
- Build number format: {branch}-{date}-{run-number}-{commit-hash}
- Produces versioned artifacts with 90-day retention
- Includes build manifest and SBOM
### 2. Create Release (create-release.yml)
- Manual trigger with version and build number selection
- Downloads specific build artifacts
- Runs RFC compliance and security validation tests
- Updates version in Directory.Build.props
- Creates git tag (v{version})
- Creates GitHub Release with artifacts
- Supports pre-release flag
### 3. Publish to NuGet (publish-nuget.yml)
- Auto-triggers when GitHub release is published
- Uses NuGet Trusted Publishing (OIDC)
- No API keys required - secure GitHub-NuGet authentication
- Downloads release artifacts
- Publishes to NuGet.org with automatic verification
- Supports manual trigger for republishing
## Key Improvements
✅ Clean separation: Build → Release → Publish
✅ Artifact-based releases (reproducible)
✅ Proper build versioning with metadata
✅ NuGet Trusted Publishing (more secure, no API key management)
✅ Better artifact retention (90 days)
✅ Comprehensive documentation
✅ SBOM generation included
✅ Build manifest for traceability
## Breaking Changes
- Old workflows archived to .github/workflows/archive/
- New workflow names and trigger patterns
- Requires NuGet Trusted Publishing setup on nuget.org
## Migration Notes
To use the new workflows:
1. Configure NuGet Trusted Publishing on nuget.org
2. Create 'production' and 'nuget-production' environments in GitHub
3. Use build-and-test.yml artifacts for releases
4. Follow new release process documented in workflows/README.md
## Files Changed
Added:
- .github/workflows/build-and-test.yml (new build pipeline)
- .github/workflows/create-release.yml (manual release creation)
- .github/workflows/publish-nuget.yml (trusted publishing)
- .github/workflows/README.md (comprehensive documentation)
Archived:
- .github/workflows/archive/build.yml
- .github/workflows/archive/release.yml
- .github/workflows/archive/nightly.yml
- .github/workflows/archive/hotfix-release.yml
- .github/workflows/archive/rollback.yml
Retained (unchanged):
- .github/workflows/security-scan.yml
- .github/workflows/dependabot-automerge.yml
🤖 Generated with Claude Code (https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
## Changes ### 1. Build Number Format Update Changed from: `branch-YYYYMMDD-run-commit` Changed to: `branch-YYYYMMDD.run.commit` Examples: - Old: `main-20241025-123-abc1234` - New: `main-20241025.123.abc1234` This provides better readability and follows common versioning patterns where dots separate version components. ### 2. Security Scan Workflow - Removed CodeQL analysis job (now using GitHub's default CodeQL setup) - Retained additional security checks: - Dependency Review (PR vulnerability scanning) - Secrets Scanning (TruffleHog) - Cryptographic Validation (RFC compliance tests) GitHub's default CodeQL setup provides: - Automatic security scanning - Always up-to-date security rules - Native integration with GitHub Security tab - No workflow maintenance needed ### 3. Documentation Updates - Updated all build number format examples - Added instructions for enabling GitHub default CodeQL - Clarified security workflow purpose ## Benefits ✅ Simpler build number format (dots vs dashes) ✅ Easier CodeQL maintenance (GitHub managed) ✅ Automatic security rule updates ✅ Reduced workflow complexity ## Configuration Required To enable GitHub default CodeQL: 1. Go to Settings → Code security and analysis 2. Enable "CodeQL analysis" (default setup) 3. Select C# as the language to scan 🤖 Generated with Claude Code (https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
## Changes
### 1. Unified Production Environment
- Changed `publish-nuget.yml` to use `production` environment (was `nuget-production`)
- Both `create-release.yml` and `publish-nuget.yml` now share the same `production` environment
- Simplifies environment management - only one production environment needed
### 2. RFC Compliance in Build Workflow
- Added RFC compliance tests to `build-and-test.yml` (package job)
- Added security validation tests to `build-and-test.yml` (package job)
- Tests run BEFORE packaging - ensures only compliant builds are packaged
- Provides early feedback on compliance issues
### 3. Documentation Updates
- Updated NuGet Trusted Publishing setup to use `production` environment
- Added validation steps section to build workflow documentation
- Clarified that compliance tests run in both build and release workflows
- Updated troubleshooting guide with correct environment name
## Benefits
✅ **Simpler Setup:** Only one environment to configure
✅ **Early Detection:** RFC compliance issues caught during build, not release
✅ **Quality Gate:** Only compliant builds are packaged
✅ **Consistent Validation:** Same tests in build and release
## NuGet Trusted Publishing Configuration
When configuring on NuGet.org, use:
- Repository: KoalaFacts/HeroCrypt
- Workflow file: `publish-nuget.yml`
- **Environment name:** `production` ← Updated!
## Workflow Validation Flow
```
Build & Test → RFC Compliance → Security Tests → Package
↓ FAIL ↓ FAIL
❌ STOP ❌ STOP
↓ PASS ↓ PASS
✅ Continue ✅ Continue
```
🤖 Generated with Claude Code (https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
… scanning
## Changes
### 1. Simplified Create Release Workflow
Removed unnecessary complexity from the release workflow:
**Removed:**
- ❌ Version updates to Directory.Build.props
- ❌ Git commits for version changes
- ❌ .NET SDK setup
- ❌ RFC compliance test re-runs
- ❌ Security validation test re-runs
- ❌ Dependency restoration and building
**Kept (Simple and Clean):**
- ✅ Version format validation
- ✅ Tag existence check
- ✅ Artifact download and verification
- ✅ Release notes generation (from input + build manifest)
- ✅ GitHub Release creation with git tag
- ✅ Artifact attachment (.nupkg, .snupkg, build-manifest.json)
### 2. Removed Custom Security Scanning
Archived `security-scan.yml` workflow to `archive/`:
- GitHub's built-in security features are more comprehensive
- CodeQL default setup provides automatic scanning
- Dependabot handles vulnerability detection
- Secret scanning available natively
- Reduces maintenance burden
### 3. Documentation Updates
- Updated create-release process documentation
- Added GitHub Security Features section
- Simplified release checklist
- Updated troubleshooting guide
- Updated archived workflows list
## Rationale
**Simplified Release:**
- Version management belongs in the build workflow, not release
- RFC compliance already validated during build (every commit)
- Re-running tests during release is redundant
- Releases should be about packaging pre-validated artifacts
- Faster release process (no build/test overhead)
**Security:**
- GitHub's native features are:
- More comprehensive
- Always up-to-date
- Better integrated
- Less maintenance
- RFC compliance tests remain in build workflow
## Workflow Philosophy
```
BUILD: Validate everything (tests, compliance, security)
↓
Package artifacts
↓
RELEASE: Take validated artifacts → Create GitHub Release
↓
PUBLISH: Publish to NuGet (trusted publishing)
```
Each stage has a clear, single responsibility.
## Benefits
✅ Simpler release workflow (7 steps vs 11)
✅ Faster releases (no rebuild/retest)
✅ Clear separation of concerns
✅ Pre-validated artifacts guarantee quality
✅ Easier to understand and maintain
✅ Leverages GitHub's native security features
🤖 Generated with Claude Code (https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
## Problem
The build workflow was failing with:
```
dotnet tool install --global Microsoft.Sbom.Tool
Unhandled exception: Could not find a part of the path
'/home/runner/.dotnet/tools/.store/microsoft.sbom.tool/4.1.2/...'
Error: Process completed with exit code 1.
```
This is a known issue with Microsoft.Sbom.Tool installation in CI environments.
## Solution
### 1. Replaced SBOM Tool
**Before:**
- Used `dotnet tool install --global Microsoft.Sbom.Tool`
- Custom sbom-tool command execution
- Fragile installation process
**After:**
- Uses `anchore/sbom-action@v0` GitHub Action
- More reliable in CI environments
- Industry-standard SBOM generation
### 2. Made SBOM Generation Optional
- Added `continue-on-error: true` to SBOM generation step
- Separated SBOM artifact upload
- Build continues successfully even if SBOM generation fails
- Main artifacts (.nupkg, .snupkg, build-manifest.json) always required
### 3. Updated Artifact Structure
**Main Artifacts** (required):
- `herocrypt-{build-number}`
- *.nupkg
- *.snupkg
- build-manifest.json
**SBOM Artifact** (optional):
- `herocrypt-{build-number}-sbom`
- sbom.spdx.json
## Benefits
✅ **Reliable Builds**: SBOM failures don't break the build
✅ **Better Tooling**: Anchore SBOM Action is industry-standard
✅ **Flexible**: SBOM is generated when possible, skipped when not
✅ **Maintained**: GitHub Action is actively maintained
✅ **Standard Format**: Uses SPDX JSON format
## SBOM Details
The SBOM (Software Bill of Materials) provides:
- Complete dependency tree
- Component licenses
- Vulnerability tracking
- Supply chain transparency
Format: SPDX 2.2 JSON
## Backward Compatibility
- All critical artifacts still generated
- Release process unchanged
- NuGet publishing unaffected
- SBOM is optional enhancement
🤖 Generated with Claude Code (https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
## Rationale SBOM (Software Bill of Materials) generation was included but marked as optional (continue-on-error: true), meaning we didn't actually require it to succeed. **If we don't care about its success, we shouldn't include it.** This violates the principle of keeping workflows simple and only including what's necessary. ## What SBOM Was For SBOM provides: - Dependency tree documentation - License tracking - Vulnerability scanning - Supply chain transparency - Regulatory compliance (some industries) ## Why Remove It 1. **Not Required**: Made optional with continue-on-error 2. **Adds Complexity**: Extra GitHub Action dependency 3. **Unclear Value**: No specific use case identified 4. **Can Add Later**: Easy to add back if needed ## What Was Removed - Anchore SBOM Action step - SBOM artifact upload - SBOM documentation ## What Remains (Clean Artifacts) Build artifacts now contain only essentials: - ✅ `*.nupkg` - NuGet package - ✅ `*.snupkg` - Symbol package - ✅ `build-manifest.json` - Build metadata ## If You Need SBOM Later SBOM can be: 1. Generated manually when needed 2. Added back to workflow if there's a specific requirement 3. Generated by NuGet.org automatically (they create SBOMs) 4. Created by security scanning tools ## Philosophy **Keep It Simple**: Only include what you actually need and use. If something is optional and allowed to fail, question whether it should be there at all. 🤖 Generated with Claude Code (https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
## What Was Deleted Removed 6 archived workflows (1,046 lines): - ❌ archive/build.yml (87 lines) - ❌ archive/release.yml (199 lines) - ❌ archive/nightly.yml (97 lines) - ❌ archive/hotfix-release.yml (332 lines) - ❌ archive/rollback.yml (249 lines) - ❌ archive/security-scan.yml (82 lines) ## Rationale ### 1. Superseded Workflows - `build.yml` → Replaced by `build-and-test.yml` - `release.yml` → Replaced by `create-release.yml` - `security-scan.yml` → Use GitHub's built-in features ### 2. Overly Complex - `hotfix-release.yml` (332 lines!) → Just use patch releases - `rollback.yml` (249 lines) → NuGet doesn't support true rollback ### 3. Unnecessary - `nightly.yml` → Can run full tests manually when needed ## Why Delete vs Archive? **Archived workflows create confusion:** - Which workflow should I use? - Is this still relevant? - Why keep code we don't use? **Git history is the real archive:** - All workflows still in git history - Can be recovered if ever needed - Clean working directory ## Current State **4 Active Workflows** (689 lines total): 1. build-and-test.yml (232 lines) - Core CI 2. create-release.yml (194 lines) - Release creation 3. publish-nuget.yml (230 lines) - NuGet publishing 4. dependabot-automerge.yml (33 lines) - Dependency automation **Zero Archived Workflows:** - No clutter - No confusion - No maintenance burden ## Philosophy > "The best code is no code. The best workflow is a deleted workflow." Keep only what's essential. Delete everything else. ## If You Need Them Later **Hotfixes:** Use patch releases (1.0.0 → 1.0.1) **Rollbacks:** Unlist on NuGet.org + publish new version **Nightly tests:** Run manually with `dotnet test` (no filter) **Old workflows:** Available in git history ## Benefits ✅ Clean and simple ✅ Easy to understand ✅ Easy to maintain ✅ No decision paralysis ✅ Clear what's active vs historical 🤖 Generated with Claude Code (https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.