release-flow

パイプラインの概要

Conventional Commits → semantic-release → Tag + Changelog
                                        → PyPI publish (trusted publishing)
                                        → Docker build + push (GHCR)
                                        → GitHub Release with assets

Conventional Commits → バージョンバンプ

プレフィックス	バンプ	例
fix:	PATCH	fix(parser): handle empty YAML blocks
feat:	MINOR	feat(cli): add --json output flag
feat!: or BREAKING CHANGE:	MAJOR	feat!: restructure artifact schema
docs:, chore:, refactor:, test:	バンプなし	docs: update README

python-semantic-release

pyproject.toml での設定:

[tool.semantic_release]
version_toml = ["pyproject.toml:project.version"]
branch = "main"
commit_message = "chore(release): {version}"
build_command = "uv build"

[tool.semantic_release.changelog]
changelog_file = "CHANGELOG.md"

[tool.semantic_release.remote]
type = "github"

GitHub Actions リリースワークフロー

3つのジョブパイプライン (release → publish-pypi → publish-docker):

ジョブ 1: Release (バージョンバンプ + タグ付け)

• python-semantic-release/python-semantic-release@v10
• 必要な権限: contents: write, id-token: write
• RELEASE_TOKEN (PAT) を使用してタグをプッシュ
• 出力: released, version, tag

ジョブ 2: PyPI (信頼できるパブリッシング)

• needs.release.outputs.released == 'true' でトリガー
• pypa/gh-action-pypi-publish@release/v1
• OIDC信頼できるパブリッシング用に id-token: write を使用 (APIキー不要)
• 環境: pypi (リポジトリ設定で PyPI プロジェクト URL を使用して設定)

ジョブ 3: Docker (マルチアーキテクチャ GHCR)

• リリースタグでチェックアウト
• マルチプラットフォーム: linux/amd64,linux/arm64
• タグ: latest, vX.Y.Z, vX.Y, vX
• レイヤーキャッシュ用に GHA キャッシュを使用
• ビルド保証アテステーションを生成

PyPI 信頼できるパブリッシング設定

1. PyPI プロジェクト設定 → 「新しいパブリッシャーを追加」
2. 設定: GitHub 所有者、リポジトリ名、ワークフローファイル名、環境名 (pypi)
3. APIキー不要 — GitHub Actions からの OIDC トークン

Docker タグ付け戦略

バージョン 3.2.1 の場合:

ghcr.io/owner/repo:latest    # ローリング最新版
ghcr.io/owner/repo:v3.2.1    # 正確なバージョン
ghcr.io/owner/repo:v3.2      # マイナー (互換性ピニング用)
ghcr.io/owner/repo:v3        # メジャー

pyproject.toml のバージョンバンプ

semantic-release がこれを自動的に処理します。pyproject.toml のバージョンは信頼できる唯一の情報源です。手動で編集しないでください。

手動/緊急リリース

# GitHub UI または CLI 経由でトリガー
gh workflow run release.yml -f force=patch  # or minor/major

リリース前のチェックリスト

1. main ですべての CI がグリーン
2. 最後のリリース以降の Conventional Commits
3. CHANGELOG を確認 (自動生成されますが検証)
4. Docker ビルドをローカルでテスト: docker build -t test .
5. main に未コミットの変更がない