クラウドで Capacitor アプリに署名してビルドする方法

クラウドで Capacitor アプリに署名してビルドするには、まず署名用素材（Android keystore、iOS 配布証明書、プロビジョニングプロファイル）を一度作成し、クラウドビルドサービスに渡します。その後、ターミナルや CI からビルドをトリガーします。サービスがネイティブプロジェクトをコンパイル・署名し、TestFlight や Google Play に直接アップロードすることも可能です。本ガイドでは、各署名ファイルの内容、Mac なしで作成する方法、Capgo Build での設定方法、そして署名付きビルドの安全な自動化方法について解説します。

「クラウドでの署名」とは何か

両ストアは署名済みバイナリのみを受け入れます。署名は、ビルドがあなた自身のものであること、およびその後変更されていないことを証明します。ローカルでは、Xcode や Android Studio がこの処理の大部分を隠蔽してくれますが、クラウドでは暗黙の前提が一切ないため、どのファイルが関わるのかを正確に把握する必要があります。

これらをGitに含めないでください。以下では、ローカルの認証情報ファイルまたはCIのシークレットストアに保存します。

Android署名

アップロード用キーストアの作成

アプリがすでにGoogle Playにある場合は、既存のkeystoreを再利用してください。Play Consoleのアップロードキーリセットを経由しない限り、別のキーで更新に署名しても拒否されます。

新規アプリの場合:

keytool -genkeypair -v \
  -storetype PKCS12 \
  -keystore release.jks \
  -alias upload \
  -keyalg RSA -keysize 2048 \
  -validity 10000

注意:

• Google Playでは、キーの有効期限が少なくとも2033年10月22日以降である必要があります。 -validity 10000 (約27年)でこれを満たせます。
• PKCS12ストアタイプでは、キーパスワードとストアパスワードは同じです。
• JDKが手元にない場合、 Android keystore ジェネレーター でブラウザから同じファイルを生成できます。

Play App Signingとアップロードキー

Google Play上の新規アプリはPlay App Signingを使用します。Googleが アプリ署名鍵 を保持し、ユーザーがダウンロードするものを再署名します。あなたのkeystoreは キーストアのアップロード。失くした場合でも、Play Console サポートに新しいアップロードキーの登録を依頼できます。つまり、失くしても大惨事ではなく、単なる遅延です。それでもバックアップは取っておきましょう。

アップロード用サービスアカウント

クラウドからアップロードするには、Google Cloud でサービスアカウントを作成し、Google Play Android Developer API を有効化して、その JSON キーをダウンロードし、Play Console の ユーザーと権限 で、アプリのリリース権限を付けてサービスアカウントを招待します。Capgo のオンボーディングなら、以下に示すように Google サインイン経由でこれを行えます。

iOSの署名

Appleの3つの要素

• Apple Distribution 証明書。 チームごとに1つあれば十分で、有効期間は1年間です。Apple は保有数を制限しているため、開発者ごとに作成しないでください。
• プロビジョニングプロファイル。 バンドル ID、証明書、プッシュ通知などの機能を紐付けます。次を使用します: App Store Connect TestFlight と App Store 用のプロファイル、および Ad Hoc 登録済みデバイスへのインストール用プロファイル。各アプリ拡張機能（ウィジェット、共有拡張機能、通知サービス）には個別のプロファイルが必要です。
• App Store Connect API キー。 以下で作成します ユーザーとアクセス > 統合 App Manager アクセス権限が必要です。 .p8 ファイルは一度しかダウンロードできません。

これらの作成には、Apple Developer チームでの管理者またはアカウント保有者の権限が必要です。

Macなしで証明書を作成する

Keychain Accessの手順にはmacOSが必要ですが、OpenSSLはどこでも使えます：

# 1. Private key and certificate signing request
openssl req -new -newkey rsa:2048 -nodes \
  -keyout dist.key -out dist.csr \
  -subj "/emailAddress=dev@example.com/CN=Example Inc/C=US"

# 2. Upload dist.csr at developer.apple.com > Certificates > + > Apple Distribution
#    and download distribution.cer

# 3. Convert and bundle into a .p12
openssl x509 -inform DER -in distribution.cer -out distribution.pem
openssl pkcs12 -export -legacy \
  -inkey dist.key -in distribution.pem \
  -out distribution.p12 -passout pass:choose-a-password

この -legacy OpenSSL 3ではこのフラグが重要です。これがないと、macOSのビルドマシンでインポートが .p12 「MAC verification failed」で失敗することがあります。ブラウザベースの iOS証明書ジェネレーター ツールなら、ターミナルを使わずに同じ手順を実行できます。

次に、デベロッパーポータルでプロビジョニングプロファイルを作成します（プロファイル > + > App Store Connect）。App IDと新しい証明書を選択して、ダウンロードします。

Capgo Buildで署名を設定する

Capgo のビルド Capgoが管理するマシン上でCapacitorアプリをコンパイル・署名するため、WindowsやLinuxからiOSをビルドできます。まずログインしてアプリを登録してください：

bunx @capgo/cli@latest login
bunx @capgo/cli@latest app add

オプションA：ガイド付きオンボーディング（推奨）

bunx @capgo/cli@latest build init --platform ios
bunx @capgo/cli@latest build init --platform android

iOSでは、オンボーディングでApp Store ConnectのAPIキーを使って、配布証明書とApp Storeプロビジョニングプロファイルを作成または再利用します。macOSでは、そのAPIキーを作成する手順も案内します。Androidでは、keystoreを作成またはインポートし、Googleサインイン経由でGoogle CloudサービスアカウントとPlay Consoleへの招待をプロビジョニングできます。最後に、最初のビルドを開始するか提案します。

オプションB：既存ファイルを保存

前のセクションのファイルがすでにある場合：

# iOS
bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --certificate ./distribution.p12 \
  --p12-password "choose-a-password" \
  --ios-provisioning-profile ./AppStore.mobileprovision \
  --apple-key ./AuthKey_ABC1234567.p8 \
  --apple-key-id ABC1234567 \
  --apple-issuer-id 00000000-0000-0000-0000-000000000000 \
  --apple-team-id TEAM123456

# Android
bunx @capgo/cli@latest build credentials save \
  --platform android \
  --keystore ./release.jks \
  --keystore-alias upload \
  --keystore-key-password "store-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-service-account.json

拡張機能を持つアプリでは、次を繰り返します： --ios-provisioning-profile 次のものを使用して： bundleId=path 各ターゲットのマッピング：

  --ios-provisioning-profile com.example.app=./App.mobileprovision \
  --ios-provisioning-profile com.example.app.widget=./Widget.mobileprovision

認証情報は次に保存されます： ~/.capgo-credentials/credentials.json、アプリIDとプラットフォームをキーとして保存されます。次を追加して --local 保存するには .capgo-credentials.json 代わりにプロジェクト内で、そのファイルを次に追加してください： .gitignore. 保存されている内容を確認するには bunx @capgo/cli@latest build credentials list.

署名済みビルドをトリガー

ネイティブプロジェクトを準備し、ビルドをリクエストします:

bun run build
bunx cap sync

# iOS: sign with the App Store profile and upload to TestFlight
bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release

# Android: sign the AAB and upload to the internal track
bunx @capgo/cli@latest build request com.example.app --platform android --build-mode release --android-track internal

ログがターミナルにストリームされます。アップロード前に、証明書の有効期限、パスワード、プロファイルのペアリングを事前スキャンで確認するため、ほとんどの署名エラーは数分ではなく数秒で検出されます。単独で実行するには bunx @capgo/cli@latest build prescan --platform ios.

便利なバリエーション:

アドホックビルドの場合、まずでデバイスのUDIDを収集します iOS UDID 検索ツール それらをプロファイルに追加します。

CIで署名済みビルドを自動化

CI では、認証情報ファイルではなく環境変数として認証情報を渡します。CLI は必要なものをそのままエクスポートします：

bunx @capgo/cli@latest build credentials manage --appId com.example.app
# choose "Export to .env"

GitHub では、1コマンドで全行をリポジトリのシークレットにプッシュし、その後ファイルを削除します：

gh secret set -f .env.capgo.com.example.app
gh secret set CAPGO_TOKEN --body "your-capgo-api-key"
rm .env.capgo.com.example.app

タグを契機に両プラットフォームへ署名してリリースするワークフロー：

name: Signed release
on:
  push:
    tags: ['v*']

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        platform: [ios, android]
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync ${{ matrix.platform }}
      - run: bunx @capgo/cli@latest build request com.example.app --platform ${{ matrix.platform }} --build-mode release
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          CAPGO_IOS_PROVISIONING_MAP_BASE64: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_BASE64 }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}

ジョブは Linux で実行されます。macOS ランナー、キーチェーンコマンド、fastlane は不要です。同じ環境変数はあらゆる CI で動作します：GitLab CI/CD 変数、Bitbucket のセキュア変数、Gitea シークレット、Azure DevOps 変数グループなど。プラットフォーム別のガイド： Bitbucket Pipelines, Gitea Actions、および GitHub Actions ドキュメント.

署名鍵の取り扱いについて

署名鍵をクラウドサービスに預ける前に、当然抱く疑問でしょう。Capgo Buildでは：

• 認証情報はローカルマシン（~/.capgo-credentials/）またはCIのシークレットストアに保存されます。Capgo が鍵を保管することはありません。
• 各ビルド時、CLI はHTTPS経由でこれらを送信します。これらはそのビルド中のみ使用され、完了後に削除されます。
• アップロードされるのは、準備されたネイティブプロジェクトのみです。Webソースの .gitや .env ファイルはアップロードされません。
• ビルドされたアプリは、App Store ConnectやGoogle Playへ直接送信されるか、リクエストに応じて期限付きのダウンロードリンクが発行されます。

トレードオフ：認証情報をローテーションするには、CIのシークレットをご自身で更新する必要があります。再エクスポートして build credentials manage ファイルを再度プッシュしてください。

有効期限とローテーション

Apple の期限は共有カレンダーに入れておきましょう。証明書の期限が切れても、すでにユーザーのデバイスにあるアプリには影響しませんが、新しいビルドができなくなります。

トラブルシューティング

その他の解決策は Capgo Build トラブルシューティングガイドにあります と Capacitor の CI/CD：よくある落とし穴.

最初の署名済みビルド以降

署名済みのネイティブビルドが必要になるのは、ネイティブ code が変更されたときだけです。JavaScript、CSS、HTML の変更なら、 live update を インストール済みのアプリに配信しましょう。プラグインやネイティブ設定を変更するリリースでは、ストアビルドを残してください。Mac ベースの環境から移行する場合は、 Capgo Build を使えば Windows から iOS アプリをビルドできます macOS なしで一連のワークフローを紹介します。