itch-publish

itch.io への公開（butler）

ビルドを itch.io のページにアップロードし、最新の状態に保ちます。ページはブラウザーで作成し、すべてのアップロードには itch.io のコマンドラインツールである butler を使います。使うコマンドはずっとひとつだけです：butler push。butler は前回のビルドとの差分を取り、変更されたものだけをアップロードします。CI/CD の詳しい説明とフラグの詳細は references/butler-ci.md にあります。

使用する場面

• itch.io のプロジェクトページの作成・更新、butler のインストールやログイン、butler push を使ったビルドのアップロード、チャンネル名の選択、アップロードのバージョン管理、または jam／デモ／リリースビルドの itch.io への公開に使用します。
• 該当するもの：butler push、butler login、チャンネル、.itch.toml、「itch で公開」、「itch にアップロード」。

使用しない場面： Steam での公開（steam-publish を使用）；jam の 範囲／計画（game-jam を使用 — このスキルの対象はアップロードの手順のみです）；ゲーム自体のビルド（エンジンのスキルを使用）。

基本的なワークフロー

1. itch.io/game/new でプロジェクトページを作成します。Kind of projectを設定します。ネイティブビルドでは Downloadable のままにし、ブラウザーでプレイできるゲームでは HTML を選択します（ウェブビルドでは必須です — 「注意点」を参照）。価格と公開範囲を設定します（準備ができるまでは「下書き」にします）。
2. butler をインストールしてログインします。itchio.itch.io/butler からダウンロードして PATH に追加し、butler login を実行します（認証のためブラウザーが開きます）。butler version で確認します。CI では代わりに BUTLER_API_KEY を使用します — リファレンスを参照してください。
3. ポータブルなビルドフォルダーを用意します — プレイヤーが実行するファイルだけを含め、余計なものは入れません。フォルダー（またはそのフォルダーをまとめた単一の .zip）をプッシュします。インストーラーや、アーカイブをさらに圧縮したものはプッシュしないでください（パッチ適用に悪影響があります。「注意点」を参照）。
4. チャンネルにプッシュします：butler push <dir> <user>/<game>:<channel>。チャンネル名によってプラットフォームタグが決まります（「パターン」を参照）。初回のプッシュではすべてをアップロードし、同じチャンネルへの次回以降のプッシュでは差分のみをアップロードします。
5. チャンネルに正しいタグが自動設定されなかった場合は、Edit game ページでプラットフォーム／HTML タグを設定し、Save をクリックします。ブラウザーゲームでは、ページも HTML に切り替え、チャンネルに ブラウザーでプレイ可能 のタグを付けます。
6. ビルドをバージョン管理します（任意ですが推奨）：--userversion 1.2.0 または --userversion-file build.txt を指定すると、プレイヤーや更新 API に表示されるバージョン文字列を管理できます。
7. 後から更新するときは、同じチャンネルに再度プッシュします。butler status <user>/<game> でチャンネルやビルドを確認し、butler push-preview で送信前にプッシュによる変更を確認できます。

パターン

1. 必要なコマンドはひとつだけ — butler push

# butler push <directory-or-zip> <user>/<game>:<channel>
butler push ./build/windows leafy/my-game:windows
butler push ./build/mac     leafy/my-game:osx
butler push ./build/linux   leafy/my-game:linux
butler push ./web           leafy/my-game:html   # browser build (also set page Kind = HTML)

2. チャンネル名でプラットフォームタグを指定（ケバブケース、小文字）

Substring in channel name -> auto-applied tag:
  win / windows  -> Windows        linux -> Linux
  mac / osx      -> macOS          android -> Android
Multiple platforms in one channel are allowed: e.g. a Java jar:
  butler push ./jar leafy/my-game:win-linux-mac
Convention: lowercase words separated by dashes (windows-beta, osx-demo, soundtrack).
Tags are only the INITIAL guess — fix them anytime on the Edit game page (then Save).

3. バージョン管理、確認、プレビュー

butler version                              # print version; confirms install + PATH
butler login                                # authorize this machine (opens browser)

# Set an explicit version string instead of itch's auto-incrementing integer:
butler push ./build leafy/my-game:windows --userversion 1.2.0
butler push ./build leafy/my-game:windows --userversion-file build_number.txt

butler status leafy/my-game                 # list channels + latest builds/versions
butler push-preview ./build leafy/my-game:windows   # NEW/MODIFIED/DELETED/SAME, uploads nothing

4. 初回、非表示、フィルター付きのプッシュ

# Hide a brand-new channel from the page until you're ready (NEW channels only):
butler push ./build leafy/my-game:windows-beta --hidden

# Exclude files from the upload without copying the folder (--ignore is repeatable):
butler push ./build leafy/my-game:windows --ignore '*.pdb' --ignore '*.dSYM'

# Preview exactly what would be sent, without sending it:
butler push ./build leafy/my-game:windows --dry-run

注意点

• インストーラーのプッシュ。 itch.io は ポータブル ビルドにパッチを適用します。インストーラー（.exe／.msi）ではパッチ適用や itch アプリの自動更新が機能せず、プレイヤーに管理者権限が必要になる場合もあります。展開済みの実行可能なフォルダーをプッシュしてください。
• 事前に圧縮されたビルド。 高度に圧縮されたアーカイブ（またはアーカイブをまとめたアーカイブ）をプッシュすると、パッチが巨大になります。わずかな変更でも、圧縮されたデータ全体を書き換えるためです。非圧縮ファイルをプッシュしてください。itch.io 側で圧縮されます。
• .zip が1つだけ入ったフォルダー。 butler は「zip の中に zip」ができるのを避けるため、自動的に解凍して中身をプッシュします。zip を中身が不透明な1つのファイルとしてアップロードしたい場合に限り、--no-auto-unzip を渡してください。
• HTML5 ゲームがダウンロードとして表示される。 2つの設定が必要です。ページの Kind を HTML に設定し、最初のプッシュ後に Edit game ページでチャンネルに playable in browser のタグを付けてください。チャンネル名だけでは、どちらも自動的に設定されません。
• 既存のチャンネルに対する --hidden でエラーが発生する。 このオプションは、プッシュによって新しいチャンネルが作成される場合にのみ適用されます。後から Edit game で非表示を解除できます。
• チャンネル名の入力ミスで重複スロットが作成される。 windows と win-final は別々のチャンネルであり、別個のダウンロードが作成されます。あらかじめチャンネル名を決め、同じ名前を使い続けてください。
• 上限は30 GB。 非圧縮時の合計サイズが30 GBを超えるビルドは、itch.io に拒否されます。
• CI ログに含まれるシークレット。 公開ログに BUTLER_API_KEY が出力された場合、そのキーは漏えいしたものと見なしてください。API keys ページで直ちに取り消してください。CI で安全に使用する方法については、リファレンスを参照してください。

リファレンス

• BUTLER_API_KEY を使った CI/CD（GitHub Actions／GitLab）、broth による自動インストール、すべてのフラグ一覧、更新チェック API については、references/butler-ci.md をお読みください。
• 主なドキュメント：butler マニュアル — itch.io/docs/butler（インストール、ログイン、プッシュ）。

関連スキル

• steam-publish — SteamPipe を使って同じゲームを Steam で公開します（itch.io と同時にリリースされることがよくあります）。
• game-jam — 多くのゲームジャムは itch.io で開催されます。このスキルはアップロード手順を扱います。
• prototype-fast — プレイテスト用に、初期のプロトタイプを Draft／アクセス制限付きの itch ページで共有します。