dotnet-github-releases

name	dotnet-github-releases
category	developer-experience
subcategory	cli
description	Creates GitHub Releases for .NET. Release creation, assets, notes, pre-release management.
license	MIT
targets	["*"]
tags	["foundation","dotnet","skill"]
version	0.0.1
author	dotnet-agent-harness
invocable	true
claudecode	{"allowed-tools":["Read","Grep","Glob","Bash","Write","Edit"]}
codexcli	{"short-description":".NET skill guidance for foundation tasks"}
opencode	{"allowed-tools":["Read","Grep","Glob","Bash","Write","Edit"]}
copilot	{}
geminicli	{}
antigravity	{}

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

• Release creation via gh CLI and GitHub API
• Asset attachment (NuGet packages, binaries, SBOMs, checksums)
• softprops/action-gh-release GitHub Actions usage
• Release notes generation strategies
• Pre-release management (draft, pre-release flag, promotion)

Out of scope

• CLI-specific release automation (build matrix, RID artifacts) -- 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) -- 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

# 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

```text

### 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  \
  --draft \
  --generate-notes


gh release edit v1.2.3 --draft=

```text



```bash


 > release-notes.md << 



- Added widget caching support
- Improved fluent API ergonomics


- Fixed memory leak  widget pool
- Corrected timezone handling  scheduler


- 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  \
  --notes-file release-notes.md

```markdown

---



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



```bash


gh release create v1.2.3 \
  --title  \
  --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

```json



```bash


gh release upload v1.2.3 \
  artifacts/myapp-osx-arm64.tar.gz \
  artifacts/myapp-linux-arm64.tar.gz


gh release upload v1.2.3 \
  artifacts/SHA256SUMS.txt --clobber

```text



| 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          |



```bash


 artifacts
 *.nupkg *.tar.gz *.zip > SHA256SUMS.txt


shasum -a 256 *.nupkg *.tar.gz *.zip > SHA256SUMS.txt

```text

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

---





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:
  runs-on: ubuntu-latest
  : startsWith(github.ref, )
  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: |
         artifacts
         *.nupkg > SHA256SUMS.txt

    - name: Create GitHub Release
      uses: softprops/action-gh-release@v2
      with:
        generate_release_notes: 
        files: |
          artifacts/*.nupkg
          artifacts/*.snupkg
          artifacts/SHA256SUMS.txt
        draft: 
        prerelease: }

```text



Two common patterns  triggering release CI:

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

```yaml

on:
  push:
    tags:
      -  

```text

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

```yaml

on:
  release:
    types: [published]

```yaml

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



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

```yaml

- name: Determine pre-release status
  : prerelease
  run: |
    TAG=
     [[  == *-* ]]; 
        >> 
    
        >> 
    

- name: Create release
  uses: softprops/action-gh-release@v2
  with:
    prerelease: }
    generate_release_notes: 

```text

---





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

```bash


gh release create v1.2.3 --generate-notes


gh release create v1.2.3 --generate-notes \
  --notes  --notes-start-tag v1.1.0

```text

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

```yaml


changelog:
  exclude:
    labels:
      - ignore-for-release
    authors:
      - dependabot
  categories:
    - title: 
      labels:
        - breaking-change
    - title: 
      labels:
        - enhancement
        - feature
    - title: 
      labels:
        - bug
        - fix
    - title: 
      labels:
        - dependencies
    - title: 
      labels:
        - 

```text



Use a maintained `CHANGELOG.md` as the release notes . For CHANGELOG format and auto-generation tooling, see
[skill:dotnet-release-management].

```bash




VERSION=
NOTES=$(sed -n  CHANGELOG.md | sed )

gh release create  \
  --title  \
  --notes 

```text



For projects using conventional commits (`feat:`, `fix:`, `chore:`), tools like `git-cliff` or `conventional-changelog`
can generate structured release notes.

```bash


git cliff --tag  --unreleased --strip header > release-notes.md

gh release create v1.2.3 \
  --title  \
  --notes-file release-notes.md

```markdown

---





Pre-releases are visible on the releases page but not shown as the  release. NuGet packages attached to
pre-releases are still stable unless they have SemVer pre-release suffixes.

```bash


gh release create v1.2.3-beta.1 \
  --title  \
  --prerelease \
  --generate-notes


gh release create v2.0.0-alpha.1 \
  --title  \
  --prerelease \
  --target feature/v2

```text



When a pre-release has been validated, promote it to a stable release:

```bash


gh release edit v1.2.3-rc.1 --prerelease=


COMMIT=$(gh release view v1.2.3-rc.1 --json targetCommitish -q .targetCommitish)
gh release create v1.2.3 \
  --title  \
  --target  \
  --notes 

```text



Use drafts to stage releases with assets before making them public:

```bash


gh release create v1.2.3 \
  --draft \
  --title  \
  --generate-notes \
  artifacts/*.nupkg artifacts/SHA256SUMS.txt




gh release edit v1.2.3 --draft=




```text



A typical pre-release progression  a .NET library:

| Stage             | Tag              | GitHub Pre-release | NuGet Version   |
| ----------------- | ---------------- | ------------------ | --------------- |
| Alpha             | `v2.0.0-alpha.1` | Yes                | `2.0.0-alpha.1` |
| Beta              | `v2.0.0-beta.1`  | Yes                | `2.0.0-beta.1`  |
| Release candidate | `v2.0.0-rc.1`    | Yes                | `2.0.0-rc.1`    |
| Stable            | `v2.0.0`         | No (Latest)        | `2.0.0`         |

---





For automation scenarios beyond the `gh` CLI:

```bash


curl -X POST \
  -H  \
  -H  \
   \
  -d 

```text



```bash


RELEASE_ID=$(gh api repos/OWNER/REPO/releases/tags/v1.2.3 --jq .)
curl -X POST \
  -H  \
  -H  \
   \
  --data-binary @artifacts/MyApp.1.2.3.nupkg

```text



```bash


gh release list


gh release view v1.2.3


gh release view --json tagName -q .tagName


gh release list --json tagName,isPrerelease,publishedAt

```json

---



1. **Never hardcode `GITHUB_TOKEN` values  examples** -- always use `` or `}`
   environment variable references. The `GITHUB_TOKEN` is automatically available  GitHub Actions.

1. **`softprops/action-gh-release` requires `permissions: contents: write`** -- without this, the action fails with a
   403 error. Always include the permissions block  the workflow job.

1. **Pre-release detection by SemVer suffix requires checking  a hyphen** -- `v1.2.3-beta.1` is pre-release, `v1.2.3`
   is stable. Use `contains(github.ref_name, )` or shell pattern matching, not regex on the version number alone.

1. **`--generate-notes` and `--notes` can be combined** -- custom notes appear first, auto-generated notes are appended.
   Use `--notes-start-tag` to control the comparison range.

1. **Draft releases  not trigger `release: published` events** -- only publishing the draft triggers the event. This
   is the intended behavior  draft-then-publish workflows.

1. **Asset filenames must be unique within a release** -- uploading a file with the same name replaces the existing
   asset only with `--clobber`. Without it, the upload fails.

1. **Tag-triggered workflows should validate the tag format** -- use `: startsWith(github.ref, )` to
   ensure the workflow only runs on version tags, not arbitrary tags.

1. **`gh release create` with `--target` creates the tag  it does not exist** -- this is useful  CI but can cause
   confusion  the tag already exists on a different commit.