capacitor-ci-cd

Capacitor アプリの CI/CD

使用する Capacitor のメジャーバージョンに適したツールチェーンを使って、CI から Capacitor アプリをビルド、署名、リリースします。

使用するタイミング

次の場合に使用します：

• .github/workflows/*.yml、.gitlab-ci.yml、fastlane/Fastfile、または Capgo Cloud Build ジョブを作成または修正するとき。
• Capacitor 8 または 9 向けに、ランナーイメージや Node／Xcode／JDK のバージョンを選ぶとき。
• 署名、TestFlight／Play へのアップロード、バージョンの更新、または Capgo OTA のアップロードを自動化するとき。
• ローカルではビルドできるのに、CI ビルドが失敗するとき。

次の用途には使用しないでください：

• 手動での提出、ストア掲載情報、スクリーンショット → capacitor-app-store。
• Capgo Cloud Build の認証情報の設定とトラブルシューティング → capgo-native-builds。
• チャネルの昇格、段階的な OTA ロールアウト → capgo-release-workflows。
• 単体テスト／E2E テストの作成 → capacitor-testing。
• セキュリティスキャンのルール → capacitor-security。

プロジェクトの現在のスナップショット

Capacitor のバージョン、Node のエンジン、スクリプト： !node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const out=[];if(pkg.engines)out.push('engines='+JSON.stringify(pkg.engines));if(pkg.packageManager)out.push('packageManager='+pkg.packageManager);for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@capacitor/')||name==='@capgo/cli'||name==='@capgo/capacitor-updater')out.push(section+'.'+name+'='+version)}}for(const [name,cmd] of Object.entries(pkg.scripts||{})){if(/build|test|lint|sync|release/i.test(name))out.push('scripts.'+name+'='+cmd)}console.log(out.join('\n'))"

既存の CI、ロックファイル、ネイティブビルドファイル： !find . -maxdepth 4 -not -path '*/node_modules/*' \( -path './.github/workflows/*' -o -name '.gitlab-ci.yml' -o -name 'Fastfile' -o -name 'Appfile' -o -name 'Matchfile' -o -name 'ExportOptions.plist' -o -name 'Podfile' -o -name 'Package.swift' -o -name 'gradle-wrapper.properties' -o -name 'variables.gradle' -o -name '.nvmrc' -o -name '.node-version' -o -name 'bun.lock' -o -name 'package-lock.json' -o -name 'pnpm-lock.yaml' -o -name 'yarn.lock' \)

ツールチェーン一覧

	Capacitor 8.x（安定版、latest）	Capacitor 9（next、GA 前）
Node	22+	24+（npm 11 が付属）
Xcode	26+（UIScene を採用済みの場合、8.5+ では 27 も可）	27+
GitHub macOS ランナー	macos-26（デフォルトの Xcode 26.x）	xcode-27 イメージ（執筆時点ではプレビュー）または Xcode 27 が記載された macos-* イメージ。actions/runner-images を確認してください
iOS デプロイメントターゲット	15.0	16.0
JDK	21	21（AGP 9 自体は 17+ が必要ですが、Capacitor の Android ライブラリは Java 21 でコンパイルされます）
Gradle／AGP	8.14.3 / 8.13	9.5.1 / 9.2.1
compile／target SDK	36	37

ストア側の期限：Apple は現在 iOS 26 SDK を、2027 年 4 月からは iOS 27 SDK を要求しています。Google Play は 2026 年 8 月 31 日以降、target API 36 を要求します。macos-26 上の Capacitor 8 アプリは、現時点で両方の要件を満たします。

複数の Xcode がインストールされている場合は、Xcode を明示的に指定します：sudo xcode-select -s /Applications/Xcode_<version>.app（正確なフォルダー名はランナーイメージの README に記載されています）。

パイプラインの形を選ぶ

不明な場合は、ユーザーに確認してください。

1. Capgo Cloud Build - macOS ランナーやローカルの署名設定は不要です。任意の Linux ランナーから npx @capgo/cli@latest build request <appId> --platform ios|android を実行します。認証情報は一度だけ npx @capgo/cli@latest build credentials save ... で保存し（または build init で iOS のガイド付きセットアップを実行し）、CI では環境変数として渡します。詳細については capgo-native-builds を読み込んでください。
2. セルフホスト型 GitHub Actions / GitLab - 完全な制御が可能です。macOS ランナー、証明書、キーストアを管理します。references/github-actions.md、references/gitlab-ci.md を参照してください。
3. どちらの場合も Fastlane を使用 - match/pilot/supply をすでに使用している場合に最適です。references/fastlane.md を参照してください。

ネイティブリリース後の Web のみの変更では、ネイティブビルドを完全に省略できます。Capgo バンドルをアップロードしてください（npx @capgo/cli@latest bundle upload --channel <channel>、認証には CAPGO_TOKEN を使用）。ネイティブの変更（プラグイン、権限、Capacitor のアップグレード）には、必ずネイティブビルドが必要です。

手順

1. スナップショットを確認します。Capacitor のメジャーバージョン、パッケージマネージャーとロックファイル、iOS の依存関係マネージャー（Package.swift -> SPM、Podfile -> CocoaPods）、既存のワークフローを確認してください。
2. マトリックスからツールチェーンのバージョンを選びます。.nvmrc / engines があれば、それに基づいて Node のバージョンを設定します。
3. ジョブを構成します。test（lint、typecheck、unit） -> build-web（アーティファクト <webDir>） -> 並列実行する ios + android -> ブランチまたはタグで制御するデプロイジョブの順にします。Web アーティファクトを復元した後、ネイティブジョブでは必ず npx cap sync <platform> を実行してください。CI の近道として、同期済みアセットをコミットしないでください。
4. 署名については references/signing-and-secrets.md に従います。Apple ID のパスワードより App Store Connect API キーを優先してください。Android のキーストアとパスワードはシークレットに保存し、実行時にデコードして、処理後に削除します。
5. ビルド番号は CI から取得します（GITHUB_RUN_NUMBER、CI_PIPELINE_IID）。または Capgo Cloud Build に採番させます。ビルド番号を再利用しないでください。
6. キャッシュを追加します（references/caching-and-versioning.md）。
7. まずブランチでパイプラインを実行し、TestFlight の内部テスト、または Play の内部テストトラックにのみアップロードします。

検証

• クリーンなランナーで、キャッシュが空の場合と温まっている場合の両方で、ワークフローが連続して 2 回成功します。
• ログに想定したツールのバージョンが表示されます。node -v、xcodebuild -version、java -version、./gradlew --version のステップを追加してください。
• iOS アーティファクト：unzip -l App.ipa | grep Payload/App.app を実行し、想定したビルド番号で TestFlight にビルドが表示されることを確認します。
• Android アーティファクト：bundletool dump manifest --bundle app-release.aab | grep -E "versionCode|targetSdkVersion" の結果が想定と一致し、Play の内部テストトラックにビルドが表示されることを確認します。
• Capgo：npx @capgo/cli@latest bundle list で、意図したチャンネルにアップロード済みのバージョンが表示されます。
• ログにシークレットの値が出力されていません（GitHub は登録済みのシークレットをマスクします。デコードしたファイルを echo しないでください）。

エラー処理

CI ログのエラー	対処方法
error ... The engine "node" is incompatible with this module. Expected version ">=22.0.0"（または >=24）	actions/setup-node の node-version を Capacitor のメジャーバージョンに合わせて更新します
Could not find the web assets directory: ./dist.	Web アーティファクトが webDir にダウンロードされていないか、ビルドがスキップされています。アーティファクトのパスを修正します
No signing certificate "iOS Distribution" found	証明書がアクティブなキーチェーンに読み込まれていないか、チームが間違っています。署名のリファレンスを参照してください
"App" requires a provisioning profile. Select a provisioning profile in the Signing & Capabilities editor.	プロファイルをインストールするか、API キー認証フラグとともに -allowProvisioningUpdates を使用します
error: exportArchive: No profiles for 'com.x.y' were found	プロファイルの種類が ExportOptions.plist の method（app-store-connect）と一致していません
xcodebuild: error: SDK "iphoneos27.0" cannot be located / @UIApplicationMain に関する Swift 6 のエラー	選択されている Xcode が間違っています。必要なバージョンを xcode-select で選択し、@UIApplicationMain を @main に置き換えます
Unsupported class file major version 65 / Android Gradle plugin requires Java 17 to run / invalid source release: 21	actions/setup-java（distribution: temurin、java-version: '21'）で JDK 21 をインストールします
Capacitor 9 へのアップグレード後に Plugin [id: 'org.jetbrains.kotlin.android'] ... が競合する	AGP 9 には Kotlin が組み込まれています。capacitor-app-upgrades に従って kotlin-android プラグインを削除します
SDK location not found. Define a valid SDK location with an ANDROID_HOME	Android SDK がインストールされたイメージ（ubuntu-latest には含まれています）を使用するか、android-actions/setup-android を使用します
Play API：APK specifies a version code that has already been used.	CI の実行番号から versionCode を設定します
Capgo：Cannot find API key in local folder or global, please login first	そのステップの env でシークレットから CAPGO_TOKEN をエクスポートするか、-a を渡します
Capgo：Cannot auth user with apikey	キーが取り消されているか、アップロード権限がありません。Capgo ダッシュボードで新しいキーを作成します
npm error 404 Not Found - GET https://registry.npmjs.org/capsec	セキュリティスキャナーパッケージは @capgo/capgo-sec です：npx @capgo/capgo-sec@latest scan --ci

参考資料

• references/github-actions.md - テスト、Web ビルド、iOS（SPM/CocoaPods）、Android、Capgo OTA、Capgo Cloud Build ジョブを含む完全なワークフロー。
• references/gitlab-ci.md - macOS ランナーのタグを使用する GitLab パイプライン。
• references/fastlane.md - API キーと match を使用する iOS および Android のレーン。
• references/signing-and-secrets.md - 証明書／プロファイルの読み込み、API キー認証、Android キーストアの設定、シークレット一覧。
• references/caching-and-versioning.md - npm/Gradle/SPM/CocoaPods のキャッシュ、ビルド番号、semantic-release。