pypi-doppler

Doppler を使用した PyPI への公開（ローカルのみ）

自己改善型スキル：このスキルは使用を通じて改善されます。手順に誤りがある場合、パラメーターが変わった場合、または回避策が必要になった場合は、先延ばしにせず直ちにこのファイルを修正してください。実際に再現可能な問題がある場合にのみ更新してください。

このスキルを使用するタイミング

次の場合にこのスキルを使用してください：

• ローカルマシンから Python パッケージを PyPI に公開するとき
• PyPI トークン管理のために Doppler を設定するとき
• CI 検出ガードを備えたローカル公開スクリプトを作成するとき
• リリース前にリポジトリの所有権を検証するとき

ワークスペース全体のポリシー：ローカルのみで公開

このスキルはローカルマシンからの公開のみをサポートします。

禁止事項

• GitHub Actions から公開すること
• CI/CD パイプライン（GitHub Actions、GitLab CI、Jenkins、CircleCI）から公開すること
• semantic-release 設定で publishCmd を使用すること
• CI でパッケージをビルドすること（prepareCmd で uv build を実行すること）
• GitHub シークレットに PyPI トークンを保存すること

必須事項

• ローカルマシンで scripts/publish-to-pypi.sh を使用すること
• 公開スクリプトに CI 検出ガードを設けること
• リリースごとに手動承認を行うこと
• Doppler で認証情報を管理すること（平文トークンは使用しない）
• リポジトリを検証すること（フォークの悪用を防止）

理由

• セキュリティ：GitHub シークレットに有効期間の長い PyPI トークンを保存しません
• 速度：CI では 3～5 分かかるところ、ローカルでは 30 秒です
• 管理：本番リリース前に手動承認の手順を設けます
• 柔軟性：Doppler を通じて認証情報を一元管理します

参照：ADR-0027、docs/development/PUBLISHING.md

---

概要

このスキルでは、認証情報を安全に管理するために Doppler を使用し、ローカルのみで PyPI に公開します。次のようなワークスペース全体のリリースワークフローと連携します。

1. GitHub Actions：自動バージョン管理のみ（タグ、リリース、CHANGELOG）
2. ローカルマシン：Doppler の認証情報を使用した手動での PyPI 公開

同梱スクリプト

スクリプト	用途
scripts/publish-to-pypi.sh	CI 検出ガードを備えたローカルからの PyPI 公開

使用方法：プロジェクトの scripts/ ディレクトリにコピーします。

/usr/bin/env bash << 'DOPPLER_EOF'
# Resolve plugin root using cc-plugin-root helper
PLUGIN_DIR="$(cc-plugin-root itp)"
cp "$PLUGIN_DIR/skills/pypi-doppler/scripts/publish-to-pypi.sh" scripts/
chmod +x scripts/publish-to-pypi.sh
DOPPLER_EOF

---

前提条件

初回のみの設定

1. Doppler CLI をインストールします：

   brew install dopplerhq/cli/doppler
   

2. Doppler で認証します：

   doppler login
   

3. private-config プロジェクトへのアクセスを確認します：

   doppler whoami
   doppler projects
   

PyPI トークンの設定

1. PyPI API トークンを作成します：

   • https://pypi.org/manage/account/token/ にアクセスします
   • まだ有効にしていない場合は 2FA を有効にします（2024 年以降必須）
   • スコープを「アカウント全体」または特定のプロジェクトにしてトークンを作成します
   • トークンをコピーします（pypi-AgEIcHlwaS5vcmc... で始まり、約 180 文字です）

2. トークンを Doppler に保存します：

   doppler secrets set PYPI_TOKEN='pypi-AgEIcHlwaS5vcmc...' \
     --project private-config \
     --config prd
   

3. トークンが保存されたことを確認します：

   doppler secrets get PYPI_TOKEN \
     --project private-config \
     --config prd \
     --plain
   

---

公開ワークフロー

必須：公開前にバージョンが上がっていることを確認する

公開前の検証：PyPI に公開する前に、前回のリリースからバージョンが上がっていることを確認します。バージョンを上げずに公開することは無効であり、リソースを無駄にします。

自動チェックの手順：

1. ローカルの pyproject.toml のバージョンと、PyPI の最新バージョンを比較します
2. バージョンが一致する場合は、停止し、公開を進めないでください
3. ユーザーに「バージョンが上がっていません。先に semantic-release を実行するか、コミットに feat: または fix: のタイプが含まれていることを確認してください。」と伝えます

リリースの全手順

ステップ 1：開発とコミット（Conventional Commits）：

git add .
git commit -m "feat: add new feature"  # MINOR bump
git push origin main

ステップ 2：自動バージョン管理（GitHub Actions - 40～60 秒）：

GitHub Actions がコミットを分析し、次のバージョンを決定し、pyproject.toml／package.json を更新して、CHANGELOG を生成し、git タグを作成し、GitHub リリースを作成します。

ここでは PyPI への公開は行われません（設計上の仕様です。ADR-0027 を参照してください）。

ステップ 3：ローカルから PyPI に公開（30 秒）：

git pull origin main
./scripts/publish-to-pypi.sh

同梱スクリプトを使用する（推奨）

/usr/bin/env bash << 'GIT_EOF'
# First time: copy script from skill to your project (resolve plugin root via cc-plugin-root)
PLUGIN_DIR="$(cc-plugin-root itp)"
cp "$PLUGIN_DIR/skills/pypi-doppler/scripts/publish-to-pypi.sh" scripts/
chmod +x scripts/publish-to-pypi.sh

# After semantic-release creates GitHub release
git pull origin main

# Publish using local copy of bundled script
./scripts/publish-to-pypi.sh
GIT_EOF

同梱スクリプトの機能：CI 検出ガード、リポジトリの検証、Doppler との連携、ビルド＋公開＋検証のワークフロー、わかりやすいエラーメッセージ。

手動で公開する（上級者向け）

標準スクリプトを使わずに手動で公開する場合：

/usr/bin/env bash << 'CONFIG_EOF'
# Retrieve token from Doppler
PYPI_TOKEN=$(doppler secrets get PYPI_TOKEN \
  --project private-config \
  --config prd \
  --plain)

# Build package
uv build

# Publish to PyPI
UV_PUBLISH_TOKEN="${PYPI_TOKEN}" uv publish
CONFIG_EOF

警告：手動での公開では、CI 検出ガードとリポジトリの検証が省略されます。特別な理由がない限り、標準スクリプトを使用してください。

---

参考ドキュメント

トピック	参考資料
CI 検出	CI 検出の適用
認証情報の管理	Doppler とトークンの管理
トラブルシューティング	トラブルシューティングガイド
TestPyPI でのテスト	TestPyPI でのテスト
タスクの依存関係	タスクの依存関係

---

関連ドキュメント

• ADR-0027: docs/architecture/decisions/0027-local-only-pypi-publishing.md - ローカルのみで公開するためのアーキテクチャ上の決定
• ADR-0028: docs/architecture/decisions/0028-skills-documentation-alignment.md - ADR-0027 に合わせたスキルの整合
• PUBLISHING.md: docs/development/PUBLISHING.md - リリースワークフローの完全ガイド
• 同梱スクリプト: scripts/publish-to-pypi.sh - CI ガードを備えたリファレンス実装

---

検証履歴

• 2025-12-03: 発見を優先し、環境に依存しない方法にリファクタリング
  • discover_uv() は PATH、直接インストール、バージョンマネージャーを優先順に確認
  • 対応方式：curl によるインストール、Homebrew、cargo、mise、asdf — 特定の方式を強制しません
• 2025-11-22: ADR-0027 に準拠して作成（ワークスペース全体でローカルのみを許可するポリシー）
• 検証：CI 検出ガードをテストし、Doppler との連携を検証済み

---

最終更新日：2025-12-03 ポリシー：ワークスペース全体でローカルのみを許可する PyPI 公開（ADR-0027） 置き換え対象：なし（当初から ADR-0027 に準拠して作成）

実行後の振り返り

このスキルの実行後、終了する前に以下を確認してください。

1. コマンドは成功しましたか？ — 成功しなかった場合は、失敗の原因となった手順またはエラーテーブルを修正してください。
2. パラメーターまたは出力に変更はありましたか？ — 基盤となるツールのインターフェースに差異が生じている場合は、使用例とパラメーターテーブルを更新して合わせてください。
3. 回避策が必要でしたか？ — 異なるフラグや追加手順などの工夫が必要だった場合は、次回同じ回避策が不要になるよう、この SKILL.md を更新してください。

問題が実際に発生し、再現可能な場合にのみ更新してください。推測に基づいて更新しないでください。