dotnet-github-releases

What this skill does

# dotnet-github-releases

GitHub Releases for .NET projects: release creation via `gh release create` CLI and GitHub API, asset attachment patterns (NuGet packages, binaries, SBOMs, checksums), `softprops/action-gh-release` GitHub Actions usage, release notes generation strategies (GitHub auto-generated, changelog-based, conventional commits), pre-release management (draft releases, pre-release flag, promoting pre-release to stable), and tag-triggered vs release-triggered workflow concepts.

**Version assumptions:** GitHub CLI (`gh`) 2.x+. `softprops/action-gh-release@v2`. GitHub REST API v3 / GraphQL API v4. .NET 8.0+ baseline.

**Scope boundary:** This skill owns GitHub Release creation and management for .NET projects -- the release lifecycle on GitHub including asset attachment, release notes, and pre-release workflows. CLI-specific release pipelines (build matrix, artifact staging, checksums, package manager PR creation) are owned by [skill:dotnet-cli-release-pipeline]. CI/CD publish workflows (NuGet push, container push) are owned by [skill:dotnet-gha-publish]. Full CI pipeline patterns (reusable workflows, matrix testing) are owned by [skill:dotnet-gha-patterns].

**Out of scope:** CLI-specific release automation (build matrix, RID-specific artifacts, package manager PRs) -- see [skill:dotnet-cli-release-pipeline]. CI/CD NuGet push and container publish workflows -- see [skill:dotnet-gha-publish]. CI pipeline structure and reusable workflows -- see [skill:dotnet-gha-patterns]. Release lifecycle strategy (NBGV, SemVer, changelogs, branching) -- see [skill:dotnet-release-management]. NuGet package authoring -- see [skill:dotnet-nuget-authoring].

Cross-references: [skill:dotnet-cli-release-pipeline] for CLI-specific release pipelines with checksums, [skill:dotnet-gha-publish] for CI publish workflows, [skill:dotnet-gha-patterns] for CI pipeline structure, [skill:dotnet-nuget-authoring] for NuGet package creation.

---

## Release Creation with GitHub CLI

### Basic Release from Tag

```bash
# Create a release from an existing tag
gh release create v1.2.3 \
  --title "v1.2.3" \
  --notes "Bug fixes and performance improvements."

# Create a release and tag simultaneously
gh release create v1.2.3 \
  --title "v1.2.3" \
  --generate-notes \
  --target main
```

### Draft Release

Draft releases are invisible to the public until published. Use drafts to stage releases while finalizing assets and notes.

```bash
# Create a draft release
gh release create v1.2.3 \
  --title "v1.2.3" \
  --draft \
  --generate-notes

# Publish the draft (promote to public)
gh release edit v1.2.3 --draft=false
```

### Release with Notes from File

```bash
# Write release notes to a file
cat > release-notes.md << 'EOF'
## What's Changed

### New Features
- Added widget caching support
- Improved fluent API ergonomics

### Bug Fixes
- Fixed memory leak in widget pool
- Corrected timezone handling in scheduler

### Breaking Changes
- Removed deprecated `Widget.Create()` overload -- use `WidgetBuilder` instead

**Full Changelog**: https://github.com/mycompany/widgets/compare/v1.1.0...v1.2.0
EOF

gh release create v1.2.0 \
  --title "v1.2.0" \
  --notes-file release-notes.md
```

---

## Asset Attachment

Attach build artifacts to a release for direct download. Common .NET assets include NuGet packages, platform-specific binaries, SBOMs, and checksum files.

### Attaching Assets at Creation

```bash
# Create release with attached assets
gh release create v1.2.3 \
  --title "v1.2.3" \
  --generate-notes \
  artifacts/MyCompany.Widgets.1.2.3.nupkg \
  artifacts/MyCompany.Widgets.1.2.3.snupkg \
  artifacts/myapp-linux-x64.tar.gz \
  artifacts/myapp-win-x64.zip \
  artifacts/sbom.spdx.json \
  artifacts/SHA256SUMS.txt
```

### Attaching Assets to Existing Release

```bash
# Upload additional assets after release creation
gh release upload v1.2.3 \
  artifacts/myapp-osx-arm64.tar.gz \
  artifacts/myapp-linux-arm64.tar.gz

# Overwrite an existing asset (same filename)
gh release upload v1.2.3 \
  artifacts/SHA256SUMS.txt --clobber
```

### Common .NET Asset Types

| Asset Type | Filename Pattern | Purpose |
|------------|-----------------|---------|
| NuGet package | `*.nupkg` | Library distribution via NuGet feeds |
| Symbol package | `*.snupkg` | Source-level debugging symbols |
| Platform binary | `myapp-{rid}.tar.gz` / `.zip` | Self-contained runtime |
| SBOM | `sbom.spdx.json` / `sbom.cdx.json` | Software Bill of Materials |
| Checksums | `SHA256SUMS.txt` | Integrity verification |
| Release notes | `RELEASE-NOTES.md` | Detailed change description |

### Generating Checksums

```bash
# Generate SHA-256 checksums for all release assets
cd artifacts
sha256sum *.nupkg *.tar.gz *.zip > SHA256SUMS.txt

# On macOS
shasum -a 256 *.nupkg *.tar.gz *.zip > SHA256SUMS.txt
```

For CLI-specific release pipelines with per-RID checksums and automated package manager PRs, see [skill:dotnet-cli-release-pipeline].

---

## GitHub Actions Release Automation

### softprops/action-gh-release

The `softprops/action-gh-release` action creates GitHub Releases from CI workflows. For full CI pipeline structure (reusable workflows, matrix strategies), see [skill:dotnet-gha-patterns]. For NuGet push and container publish steps, see [skill:dotnet-gha-publish].

```yaml
# Release job (add to your CI workflow)
release:
  runs-on: ubuntu-latest
  if: startsWith(github.ref, 'refs/tags/v')
  permissions:
    contents: write
  steps:
    - uses: actions/checkout@v4

    - name: Build and pack
      run: |
        dotnet build --configuration Release
        dotnet pack --configuration Release --output ./artifacts

    - name: Generate checksums
      run: |
        cd artifacts
        sha256sum *.nupkg > SHA256SUMS.txt

    - name: Create GitHub Release
      uses: softprops/action-gh-release@v2
      with:
        generate_release_notes: true
        files: |
          artifacts/*.nupkg
          artifacts/*.snupkg
          artifacts/SHA256SUMS.txt
        draft: false
        prerelease: ${{ contains(github.ref_name, '-') }}
```

### Tag-Triggered vs Release-Triggered Workflows

Two common patterns for triggering release CI:

**Tag-triggered** -- the workflow runs when a version tag is pushed:

```yaml
on:
  push:
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+*'  # Matches v1.2.3, v1.2.3-beta.1
```

**Release-triggered** -- the workflow runs when a GitHub Release is published:

```yaml
on:
  release:
    types: [published]
```

| Pattern | Pros | Cons |
|---------|------|------|
| Tag-triggered | Simple, single event, works with NBGV | Release must be created in workflow |
| Release-triggered | Draft-then-publish workflow, manual gating | Requires two-step process |

### Pre-release Detection in CI

Automatically mark releases as pre-release based on SemVer suffix:

```yaml
- name: Determine pre-release status
  id: prerelease
  run: |
    TAG="${GITHUB_REF_NAME}"
    if [[ "$TAG" == *-* ]]; then
      echo "is_prerelease=true" >> "$GITHUB_OUTPUT"
    else
      echo "is_prerelease=false" >> "$GITHUB_OUTPUT"
    fi

- name: Create release
  uses: softprops/action-gh-release@v2
  with:
    prerelease: ${{ steps.prerelease.outputs.is_prerelease }}
    generate_release_notes: true
```

---

## Release Notes Generation

### GitHub Auto-Generated Notes

GitHub can auto-generate release notes from merged PRs and commits since the last release.

```bash
# Use auto-generated notes
gh release create v1.2.3 --generate-notes

# Auto-generated notes with custom header
gh release create v1.2.3 --generate-notes \
  --notes "## Highlights
- Major performance improvements in widget processing

---
" --notes-start-tag v1.1.0
```

Configure auto-generated note categories in `.github/release.yml`:

```yaml
# .github/release.yml
changelog:
  exclude:
    labels:
      - ignore-for-release
    authors:
      - dependabot
  categories:
    - title: "Breaking Changes"
      labels:
        - breaking-change
    - title: "New Feat