Capacitor アプリをクラウドで署名・ビルドする方法

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

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

どちらのストアも、署名済みのバイナリのみを受け付けます。署名は、ビルドがあなた自身によって作成され、その後改ざんされていないことを証明するものです。ローカル環境では、XcodeやAndroid Studioがこれらのプロセスの多くを隠蔽してくれます。しかし、クラウド環境ではすべてを明示的に指定する必要があるため、どのファイルが関与しているのかを正確に把握しておく必要があります。

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

Androidの署名

アップロード用keystoreの作成

アプリがすでに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 certificate チームごとに1つあれば十分で、有効期限は1年です。Appleによって作成数に制限があるため、開発者ごとに作成しないでください。
• プロビジョニングプロファイル。 Bundle ID、証明書、プッシュ通知などの機能を紐付けます。使用するのは App Store Connect のプロファイル（TestFlightとApp Store用）、および Ad Hoc のプロファイル（登録済みデバイスへのインストール用）です。各App Extension（ウィジェット、Share Extension、Notification Serviceなど）には、個別のプロファイルが必要です。
• App Store ConnectのAPIキー。 作成場所： ユーザーとアクセス > 連携 （App Manager権限が必要）。この .p8 ファイルは一度しかダウンロードできません。

これらを作成するには、Apple DeveloperチームのAdminまたはAccount Holder権限が必要です。

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証明書ジェネレーター を使用すれば、ターミナルを使わずに同じ手順を実行できます。

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

Capgo Buildで署名をセットアップ

Capgo Build 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. Check what is saved with 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

Logs stream into your terminal. A pre-build scan checks certificate expiry, passwords, and profile pairing before anything is uploaded, so most signing mistakes fail in seconds instead of minutes. Run it on its own with bunx @capgo/cli@latest build prescan --platform ios.

便利なバリエーション：

ad hoc ビルドを行う場合は、まず以下のツールで iOS UDID 検索ツール を使用してデバイスの UDID を収集し、プロファイルに追加してください。

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

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

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

GitHub を使用して、1つのコマンドですべての行をリポジトリの secrets にプッシュし、その後ファイルを削除します：

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 ランナーも、keychain コマンドも、fastlane も不要です。GitLab CI/CD variables、Bitbucket secured variables、Gitea secrets、Azure DevOps variable groups など、あらゆる CI で同じ環境変数が利用可能です。プラットフォーム別の手順： 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：よくある落とし穴.

最初の署名済みビルドの後

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