GitHub ActionsでiPad用のipaを生成してAltStoreで動かすまでにハマったこと

Posted at 2026-06-05

Windows11上で作成したBevyベースのゲームをAltStoreでiPadへ移植するまでにハマったことを共有します。

Windows 11上で作成したBevyベースのゲームをiPad mini（第5世代）, iPhone15 Plusへ移植・テストするにあたり、数々の「Appleの壁」に阻まれて激しくハマったので、解決策をメモとして共有します。

ちなみに、Androidへの移植は bevy/examples/mobile を参考にしてすんなり動きました(Xiaomi Pad 7で確認）。やはりiOS/iPadOSまわりは一筋縄ではいきません。

🛑 なぜこの構成（GitHub Actions + AltStore）なのか？

最初はWindows上でクロスコンパイルを試みましたが、xbuild などのツールでは上手くいかず（x devices でiPadがどうしても認識されない）、Macも手元にない状態でした。

そこで、GitHub Actions（macOSランナー）を使ってipaファイルを自動生成し、Windows 11に導入したAltServer / AltStoreを経由してiPadにインストールするという方法を採りました。
※ご存知の通り、.ipa ファイルの実体は単なるzipアーカイブ（拡張子が違うだけ）です。

しかし、環境構築からビルド、実機転送に至るまでトラップだらけでした。

🛠️ ハマりどころと解決策

1. iCloudの再インストールで「既により新しいバージョンがインストール済みです」と弾かれる

AltServerの動作にはWindows版のiCloud（通常版）が必須ですが、過去のアンインストールの残骸があると、再インストール時にエラーが出て頑なに拒否されます。

【解決策】PowerShellでApple関連のパッケージを根こそぎ消去する

通常のコントロールパネルからの削除ではレジストリ等に幽霊データが残るため、PowerShellを管理者モードで起動し、パッケージ管理コマンドで強制削除します。

# 1. 現在インストールされているApple/iCloud関連のパッケージを確認
Get-Package | Where-Object { $_.Name -match "Apple|iCloud" }

# 2. 発見したパッケージを個別に削除
Get-Package -Name "iCloud" | Uninstall-Package

# 3. 念のためApple関連をまとめて削除
Get-Package *Apple* | Uninstall-Package

再度、最初の確認コマンドを実行すると以下の2つが残る場合があります：

Name                                  Version      Source  ProviderName
----                                  -------      ------  ------------ 
Apple, Inc. - USBDevice - 5...        msu 
Apple - Net - 7/15/2013 12:...        msu

これらはOS層のハードウェアドライバなので無視して大丈夫です。この状態でPCを再起動し、公式サイトからダウンロードした iCloudSetup.exe を実行すると無事にインストールに成功します。

2. iTunesは必ず「Apple公式サイト版」を使う

Microsoft ストア版のiTunesを入れると、AltServerがiPhone/iPadを認識してくれません。

【解決策】

必ずAppleの公式サイトから直接インストーラー（iTunes64Setup.exe）をダウンロードしてください。
👉 Windows用iTunes（64ビット版）ダウンロードリンク

インストール後、iTunesを開いてiPadが認識されていることを必ず確認します。ここを突破すると、AltServerのメニュー（Install AltStore）にiPadの名前が表示されるようになります。

3. AltStore起動時の「信頼されていないデベロッパ」エラー

iPadにAltStoreは入ったものの、起動しようとするとセキュリティエラーになります。

【解決策】iPad側でデベロッパーを信頼する

iPadの 「設定」 → 「一般」 → 「VPNとデバイス管理」 を開く
「デベロッパアプリ」の項目に自分のApple ID（メールアドレス）が表示されているのでタップ
「（Apple ID）を信頼」 を選択

これでAltStoreが起動できるようになります。起動時に「ローカルネットワーク上のデバイスへのアクセスを許可しますか？」と聞かれるので、必ず「許可」にしてください。
（7日ごとの再署名やアプリ更新の際、PC上のAltServerと通信するために必要です）。

4. 【最凶のハマり所】自作のipaが「不正なファイルフォーマット」で読み込めない

環境が整い、いざGitHub Actionsでビルドした .ipa をiPadのSafariからダウンロードし、AltStoreの「My Apps」からインポート（＋ボタン）しようとすると、「不正なファイルフォーマットなので読み込めない」というエラーが連発しました。

Info.plist やワークフローのYAMLファイルをいくら疑っても原因が見つかりません。

【原因と解決策】zipをダミーフォルダに入れる「マジック」

結論から言うと、GitHub Actions（macOS）上で普通に Payload フォルダを直にzip固めして拡張子を .ipa に変えただけでは、AltStore側がフォーマット異常と判定してしまうようです。

「ダミーの空フォルダを作成し、その中にipaファイルを生成してArtifactにアップロードする」 という手順を踏むことで、この謎のフォーマットエラーを完全に回避できました。

❌ 失敗していたActions内の処理（シェルスクリプト / YAML）

# Payloadフォルダを直接ipa化
zip -r BundleName.ipa Payload

- name: Upload IPA
  uses: actions/upload-artifact@v4
  with:
    name: my-game-ipa
    path: BundleName.ipa

⭕ 成功した修正後の処理

# dummyフォルダを作り、その中にipaを生成する
rm -rf dummy
mkdir dummy
zip -r dummy/BundleName.ipa Payload

- name: Upload IPA
  uses: actions/upload-artifact@v4
  with:
    name: my-game-ipa
    path: dummy/  # フォルダごとアップロード指定する

📱 iPadへのインストール手順

環境が整えば、以下の手順でサクッと実機に転送してデバッグできます。

iPadのSafariでGitHubのリポジトリにアクセスする（※他のブラウザだと挙動が変わる可能性があるためSafari推奨）
Actions タブから該当のワークフローを開き、一番下にある Artifacts からzipファイルをダウンロード
iPadの「ファイル」アプリを開き、ダウンロードしたzipをタップして解凍 ➔ 中から .ipa ファイルが出現
AltStoreを開き、下部の My Apps ➔ 左上の 「＋」 をタップ
先ほどの .ipa ファイルを選択
インストールが完了すると、Active にアプリ名が表示され、ホーム画面にBevyゲームのアイコンが出現します！

まとめ

Windows11 + Bevyという、Appleから遠い環境からでも、GitHub ActionsとAltStoreを組み合わせることでMacレスでiPad実機デバッグまで持っていくことができました。

同じように「不正なファイルフォーマット」や「iCloudのインストール拒否」で数時間を無駄にする人が減ることを祈ります！

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up