dotnet-github-releases

dotnet-github-releases

.NET プロジェクト向けの GitHub Releases：gh release create CLI と GitHub API によるリリース作成、アセット添付のパターン（NuGet パッケージ、バイナリ、SBOM、チェックサム）、softprops/action-gh-release GitHub Actions の使用方法、リリースノートの生成戦略（GitHub による自動生成、変更履歴ベース、Conventional Commits）、プレリリース管理（ドラフトリリース、プレリリースフラグ、プレリリースから安定版への昇格）、タグ起点とリリース起点のワークフローの概念。

バージョンの前提条件： GitHub CLI (gh) 2.x 以降。softprops/action-gh-release@v2。GitHub REST API v3 / GraphQL API v4。.NET 8.0 以降を基準とします。

対象範囲： このスキルは、.NET プロジェクト向けの GitHub Release の作成と管理を担当します。つまり、アセットの添付、リリースノート、プレリリースのワークフローなど、GitHub 上のリリースライフサイクルを対象とします。CLI 固有のリリースパイプライン（ビルドマトリックス、アーティファクトのステージング、チェックサム、パッケージマネージャーの PR 作成）は [skill:dotnet-cli-release-pipeline] が担当します。CI/CD の公開ワークフロー（NuGet の push、コンテナーの push）は [skill:dotnet-gha-publish] が担当します。CI パイプライン全体のパターン（再利用可能なワークフロー、マトリックステスト）は [skill:dotnet-gha-patterns] が担当します。

対象外： CLI 固有のリリース自動化（ビルドマトリックス、RID 固有のアーティファクト、パッケージマネージャーの PR）については、[skill:dotnet-cli-release-pipeline] を参照してください。CI/CD の NuGet push とコンテナー公開ワークフローについては、[skill:dotnet-gha-publish] を参照してください。CI パイプラインの構造と再利用可能なワークフローについては、[skill:dotnet-gha-patterns] を参照してください。リリースライフサイクル戦略（NBGV、SemVer、変更履歴、ブランチ戦略）については、[skill:dotnet-release-management] を参照してください。NuGet パッケージの作成については、[skill:dotnet-nuget-authoring] を参照してください。

相互参照：[skill:dotnet-cli-release-pipeline] はチェックサムを含む CLI 固有のリリースパイプラインについて、[skill:dotnet-gha-publish] は CI 公開ワークフローについて、[skill:dotnet-gha-patterns] は CI パイプラインの構造について、[skill:dotnet-nuget-authoring] は NuGet パッケージの作成について参照してください。

---

GitHub CLI によるリリースの作成

タグからの基本的なリリース

# 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

ドラフトリリース

ドラフトリリースは公開されるまで一般に表示されません。アセットやリリースノートを仕上げている間、リリースを準備するにはドラフトを使用します。

# 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

ファイルからリリースノートを指定したリリース

# 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

---

アセットの添付

ビルドアーティファクトをリリースに添付して、直接ダウンロードできるようにします。一般的な .NET アセットには、NuGet パッケージ、プラットフォーム固有のバイナリ、SBOM、チェックサムファイルがあります。

リリース作成時にアセットを添付する

# 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

既存のリリースにアセットを添付する

# 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

一般的な .NET アセットの種類

アセットの種類	ファイル名のパターン	用途
NuGet パッケージ	*.nupkg	NuGet フィードを通じたライブラリの配布
シンボルパッケージ	*.snupkg	ソースレベルのデバッグシンボル
プラットフォームバイナリ	myapp-{rid}.tar.gz / .zip	自己完結型ランタイム
SBOM	sbom.spdx.json / sbom.cdx.json	ソフトウェア部品表
チェックサム	SHA256SUMS.txt	整合性の検証
リリースノート	RELEASE-NOTES.md	変更内容の詳細

チェックサムの生成

# 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

RID ごとのチェックサムやパッケージマネージャーの PR 自動作成を含む CLI 固有のリリースパイプラインについては、[skill:dotnet-cli-release-pipeline] を参照してください。

---

GitHub Actions によるリリースの自動化

softprops/action-gh-release

softprops/action-gh-release アクションは、CI ワークフローから GitHub Releases を作成します。CI パイプライン全体の構造（再利用可能なワークフロー、マトリックス戦略）については、[skill:dotnet-gha-patterns] を参照してください。NuGet の push とコンテナー公開の手順については、[skill:dotnet-gha-publish] を参照してください。

# 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, '-') }}

タグトリガー型ワークフローとリリーストリガー型ワークフロー

リリース CI をトリガーする一般的なパターンは 2 つあります。

タグトリガー型 -- バージョンタグがプッシュされたときにワークフローが実行されます。

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

リリーストリガー型 -- GitHub Release が公開されたときにワークフローが実行されます。

on:
  release:
    types: [published]

パターン	メリット	デメリット
タグトリガー型	シンプルで、単一のイベントで済み、NBGV と連携できます	リリースをワークフロー内で作成する必要があります
リリーストリガー型	下書きを作成してから公開するワークフローで、手動の承認ゲートを設けられます	2 段階のプロセスが必要です

CI でのプレリリース検出

SemVer のサフィックスに基づいて、リリースをプレリリースとして自動的にマークします。

- 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

---

リリースノートの生成

GitHub による自動生成ノート

GitHub では、前回のリリース以降にマージされた PR とコミットから、リリースノートを自動生成できます。

# 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

.github/release.yml で自動生成ノートのカテゴリを設定します。

# .github/release.yml
changelog:
  exclude:
    labels:
      - ignore-for-release
    authors:
      - dependabot
  categories:
    - title: "Breaking Changes"
      labels:
        - breaking-change
    - title: "New Features"
      labels:
        - enhancement
        - feature
    - title: "Bug Fixes"
      labels:
        - bug
        - fix
    - title: "Dependencies"
      labels:
        - dependencies
    - title: "Other Changes"
      labels:
        - "*"

変更履歴ベースのノート

管理されている CHANGELOG.md をリリースノートのソースとして使用します。CHANGELOG の形式と自動生成ツールについては、[skill:dotnet-release-management] を参照してください。

# Extract the section for this version from CHANGELOG.md
# Note: requires a subsequent ## [ section as delimiter. For the last section:
#   sed -n "/^## \[${VERSION}\]/,\$p" CHANGELOG.md | sed '1d'
VERSION="1.2.3"
NOTES=$(sed -n "/^## \[${VERSION}\]/,/^## \[/p" CHANGELOG.md | sed '1d;$d')

gh release create "v${VERSION}" \
  --title "v${VERSION}" \
  --notes "$NOTES"

Conventional Commits のノート

Conventional Commits（feat:、fix:、chore:）を使用するプロジェクトでは、git-cliff や conventional-changelog などのツールで構造化されたリリースノートを生成できます。

# Generate release notes from conventional commits using git-cliff
git cliff --tag "v1.2.3" --unreleased --strip header > release-notes.md

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

---

プレリリースの管理

プレリリースフラグ

プレリリースはリリースページに表示されますが、「最新」リリースとしては表示されません。プレリリースに添付された NuGet パッケージは、SemVer のプレリリースサフィックスが付いていない限り、安定版として扱われます。

# Create a pre-release
gh release create v1.2.3-beta.1 \
  --title "v1.2.3-beta.1" \
  --prerelease \
  --generate-notes

# Create a pre-release from a specific branch
gh release create v2.0.0-alpha.1 \
  --title "v2.0.0-alpha.1" \
  --prerelease \
  --target feature/v2

プレリリースから安定版への昇格

プレリリースの検証が完了したら、安定版リリースに昇格させます。

# Remove pre-release flag
gh release edit v1.2.3-rc.1 --prerelease=false

# Or create a new stable release pointing to the same commit
COMMIT=$(gh release view v1.2.3-rc.1 --json targetCommitish -q .targetCommitish)
gh release create v1.2.3 \
  --title "v1.2.3" \
  --target "$COMMIT" \
  --notes "Stable release based on v1.2.3-rc.1. No changes from RC."

下書き作成後に公開するワークフロー

アセットを含むリリースを準備してから公開するには、下書きを使用します。

# 1. CI creates a draft release with all assets
gh release create v1.2.3 \
  --draft \
  --title "v1.2.3" \
  --generate-notes \
  artifacts/*.nupkg artifacts/SHA256SUMS.txt

# 2. Team reviews the draft on GitHub

# 3. Publish the draft when ready
gh release edit v1.2.3 --draft=false

# 4. A release-triggered workflow picks up the published event
#    and pushes NuGet packages to nuget.org

プレリリースの段階

.NET ライブラリで一般的なプレリリースの進行例です。

段階	タグ	GitHub のプレリリース	NuGet のバージョン
アルファ	v2.0.0-alpha.1	はい	2.0.0-alpha.1
ベータ	v2.0.0-beta.1	はい	2.0.0-beta.1
リリース候補	v2.0.0-rc.1	はい	2.0.0-rc.1
安定版	v2.0.0	いいえ（最新）	2.0.0

---

GitHub API によるリリース管理

API によるリリースの作成

gh CLI 以外を使った自動化のシナリオでは、次のようにします。

# Create a release via GitHub REST API
curl -X POST \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/OWNER/REPO/releases" \
  -d '{
    "tag_name": "v1.2.3",
    "target_commitish": "main",
    "name": "v1.2.3",
    "body": "Release notes here",
    "draft": false,
    "prerelease": false
  }'

API によるアセットのアップロード

# Upload an asset to an existing release (REST API needs numeric release ID)
RELEASE_ID=$(gh api repos/OWNER/REPO/releases/tags/v1.2.3 --jq .id)
curl -X POST \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  "https://uploads.github.com/repos/OWNER/REPO/releases/${RELEASE_ID}/assets?name=MyApp.nupkg" \
  --data-binary @artifacts/MyApp.1.2.3.nupkg

リリースの一覧表示とクエリ

# List all releases
gh release list

# View a specific release
gh release view v1.2.3

# Get latest release tag
gh release view --json tagName -q .tagName

# List releases as JSON for scripting
gh release list --json tagName,isPrerelease,publishedAt

---

エージェントが注意すべき点

1. 例に GITHUB_TOKEN の値をハードコードしないでください -- 常に $GITHUB_TOKEN または ${{ secrets.GITHUB_TOKEN }} 環境変数の参照を使用します。GITHUB_TOKEN は GitHub Actions で自動的に利用できます。

2. softprops/action-gh-release には permissions: contents: write が必要です -- これがないと、アクションは 403 エラーで失敗します。ワークフローのジョブには必ず permissions ブロックを含めてください。

3. SemVer サフィックスによるプレリリース検出では、ハイフンの有無を確認する必要があります -- v1.2.3-beta.1 はプレリリースで、v1.2.3 は安定版です。バージョン番号だけを正規表現で判定するのではなく、contains(github.ref_name, '-') またはシェルのパターンマッチングを使用してください。

4. --generate-notes と --notes は併用できます -- カスタムノートが先に表示され、自動生成ノートがその後に追加されます。比較範囲を制御するには --notes-start-tag を使用してください。

5. 下書きリリースでは release: published イベントはトリガーされません -- イベントがトリガーされるのは、下書きを公開したときだけです。これは下書き作成後に公開するワークフローの意図された動作です。

6. リリース内のアセットファイル名は一意でなければなりません -- 同じ名前のファイルをアップロードすると、--clobber を指定した場合にのみ既存のアセットが置き換えられます。指定しない場合、アップロードは失敗します。

7. タグトリガー型ワークフローではタグ形式を検証してください -- if: startsWith(github.ref, 'refs/tags/v') を使用して、任意のタグではなくバージョンタグの場合にのみワークフローが実行されるようにします。

8. --target を指定した gh release create は、タグが存在しない場合に作成します -- CI では便利ですが、タグがすでに別のコミットを指している場合に混乱を招くことがあります。