※ vup-and-release-whl（runbook）を「自動実行スキル」として機械的に再現できるよう、入出力と確認手順を固定した版。

目的

• version up（patch +1）→ commit → push → build → GitHub/GitLab へ upload + tag + release（+ link/asset）を一括で実行する。

入力（このスキルがユーザーに確認すること）

任意（必要に応じてユーザーへ確認）:

• リリース対象タグ（例: v0.3.27）
  • 既定: v<pyproject.tomlのversion>
• Release description
  • 既定: 差分から生成（GitLab: --generate-description、GitHub: スクリプトのデフォルト動作）

前提（環境）

共通

このスキルでは http_request ツールを使用しない。外部API操作は配布スクリプト（upload_whl_github.py / upload_whl_http.py）経由で行う。

必要ツール:

• git
• python
• python -m build
• python -m ruff
• python -m black

GitLab へ配布する場合

必須環境変数:

• GITLAB_HOST
• GITLAB_PROJECT_ID
• GITLAB_TOKEN

任意:

• GITLAB_GENERIC_PACKAGE_NAME（既定 uag）
• GITLAB_GENERIC_VERSION（通常不要。wheel名から自動抽出）

GitHub へ配布する場合

必須環境変数:

• GITHUB_TOKEN

リポジトリ名は git remote get-url origin から自動取得する。 GITHUB_REPO は使用しない。

危険操作（必ず事前に確認する）

このスキルはリモートへ変更を加えます。実行前に必ず次をユーザーへ提示し、 「実行して」 と返答された場合のみ続行する。

確認文（固定）:

• 最新のコミット履歴に基づき、CHANGELOG.md（英語版）および CHANGELOG.ja.md（日本語版）の変更履歴を自動で更新/新規作成します
• pyproject.toml の version を更新するか確認します
• ユーザーが希望する場合のみ patch +1 と合わせて変更履歴（CHANGELOG）ファイルを commit します
• origin/main に push します
• wheel をビルドします（python -m build）
• 配布先（GitHub/GitLab）へ最新 whl をアップロードします
• tag vX.Y.Z を HEAD に作成します
• Release vX.Y.Z を作成/存在確認し、成果物を紐付けます
  • GitLab: Release asset link を追加（同名リンクがあれば上書き）
  • GitHub: Release asset（whl）をアップロード（同名assetがあれば削除して再アップロード）

実行フロー（固定）

0) 作業ツリー確認

• git status が clean であること。

0-A) 配布先の自動判定

git remote origin の URL から配布先を自動判定する（「入力」欄から削除し、確認不要にした）。

判定ルール:

1. git remote get-url origin の出力に github.com が含まれる → GitHub
2. 上記以外で gitlab が含まれる → GitLab
3. どちらでもない → エラー（スキル中断）

必要に応じて、判定後に該当する環境変数がすべて設定されているか確認する（設定漏れはこの時点でエラー）。

0-B) Ruff/Black による自動修正

• バージョン更新・CHANGELOG作成より前に、全 Python コードを自動修正する。
• python -m ruff check src tests --fix
• python -m black src tests
• 自動修正後に、次のコマンドで問題がないことを確認する。
  • python -m ruff check src tests
  • python -m black --check src tests
• フォーマッタが変更したファイルも、今回のリリースコミットに含める。

0-C) CHANGELOGの自動作成/更新

• 最新のコミット履歴（git log）および今回の追加機能（差分）に基づき、CHANGELOG.md（英語）および CHANGELOG.ja.md（日本語）の双方に変更内容（バージョンアップに含む全変更点）を自動で作成または追記する。

1) patch version +1

• pyproject.toml の [project].version を X.Y.Z → X.Y.(Z+1) に更新。
• 差分確認: git diff -- pyproject.toml

2) commit

• git add -- pyproject.toml CHANGELOG.md CHANGELOG.ja.md src tests（Ruff/Blackの修正を含む）
• git commit -m "Bump version to X.Y.Z and update CHANGELOG"

3) push

• git push origin main

4) build

• python -m pip install -U build
• python -m build

5A) tag/release/upload（GitLab）

• tag名: vX.Y.Z
• ref: HEAD（実体は git rev-parse HEAD の commit SHA）

実行コマンド（テンプレ・固定）:

python upload_whl_http.py --latest dist \
  --tag vX.Y.Z \
  --create-tag --tag-ref <COMMIT_SHA> \
  --ensure-release --release-ref <COMMIT_SHA> \
  --generate-description \
  --overwrite-link

5B) tag/release/upload（GitHub）

• tag名: vX.Y.Z
• target: HEAD（実体は git rev-parse HEAD の commit SHA）

実行コマンド（テンプレ・固定）:

python upload_whl_github.py --latest dist \
  --tag vX.Y.Z \
  --create-tag --target <COMMIT_SHA> \
  --create-release

補足:

• upload_whl_github.py は Release 作成時の本文を、既定で「直前タグとの差分」から生成します。
  • 固定したい場合は --release-body（スクリプト側オプション）を使います。

成功判定（検証）

• git status が clean（想定通り）
• git push が成功
• dist/ に新しい .whl が生成されている
• 配布スクリプトの出力が成功を示す（例: HTTP 201 / asset upload成功メッセージ）

失敗時のよくある原因

• GitLab: 401 Unauthorized / invalid_token: GITLAB_TOKEN の期限切れ。新しい token を発行して環境変数を更新。
• GitHub: 401/403: GITHUB_TOKEN 権限不足（contents: write）。
• push 失敗: 権限、ブランチ保護、ネットワーク。
• build 失敗: build依存関係不足、pyproject設定。