limrun-gradle

リモート Gradle ビルド

Linux、Windows、macOS、VM、コンテナなど、あらゆる環境から Limrun のリモート Gradle サンドボックス上で Android プロジェクトをビルドできます。lim gradle build はソースをリモートインスタンスに同期し、そこでプロジェクト独自の Gradle ラッパーを実行して、ビルド出力をストリーミングします。このワークフローではリモートインスタンス上でビルドするため、ローカル Gradle、ローカル Android SDK、ローカルエミュレーターは使用しません。実行が完了すると、アプリが Limrun エミュレーター上で起動するか、成果物が配信されます。

iOS ビルドには、このスキルの代わりに limrun-xcode を使用してください。どちらのプラットフォームでも Expo の開発クライアントループ（Metro、ホットリロード）を使う場合は、limrun-expo-development を使用してください。Android Debug ビルドでは、ここに戻ってきます。

認証と CLI

必要であれば、次のコマンドでインストールします：npm install --global lim。認証には lim login または LIM_API_KEY を使用します（.env やシェルに表示されなくても、ユーザーの環境にすでに設定されている場合があります。認証情報を求める前に確認してください）。CLI が正式な情報源です。このスキルに記載されたコマンドは検証済みですが、フラグでエラーが発生した場合や、ここに記載のないフラグが必要な場合は、推測せずに --help を確認してください：

lim gradle --help
lim gradle build --help

APK をビルドする

./gradlew の代わりに、次のコマンドでビルドします：

lim gradle build .

これにより、Gradle インスタンスが作成または再利用され、現在のディレクトリが同期され、デフォルトで assembleDebug が実行されます。--task（繰り返し指定可能）を使って、タスクを明示的に選択できます：

lim gradle build . --task :app:assembleRelease

Gradle のルートがサブディレクトリにあり、自動検出が曖昧な場合は --project-path を使用してください（たとえば、Gradle が android/ にある素の React Native リポジトリの場合などです。通常はサーバーが自動で検出します）：

lim gradle build . --project-path android

Expo のマネージドワークフロープロジェクト（android/ ディレクトリがない場合）は自動検出されます。サンドボックスが依存関係をインストールし、Gradle の前に expo prebuild を実行します。--expo-app-dir（モノレポの場合）または --abi を設定すると、このパイプラインが強制され、Expo アプリが検出されない場合はエラーになります：

lim gradle build ./my-monorepo --expo-app-dir apps/mobile

通常のビルドではなく、Metro とホットリロードを使って Expo アプリを反復開発する場合は、limrun-expo-development を使用してください。

プライベートな依存関係の認証情報

既存の認証情報ファイルは --additional-file でコピーできます。このフラグは sync でもサポートされています：

lim gradle build . \
  --additional-file "$HOME/.npmrc=~/.npmrc" \
  --additional-file "$HOME/.netrc=~/.netrc"

リモートの ~/ はサンドボックスのホームディレクトリを指します。それ以外の宛先はワークスペースからの相対パスです。ファイルを保持するには、後続の同期でもフラグを繰り返し指定してください。設定で参照されている環境変数には --env を渡します。

切り離されたビルドとログ

--detach を使うと、ビルドが受け付けられた時点で戻ります。Webhook の指定は任意です。logs は exec ID がなくても最新のビルドを読み込みます。インスタンス削除後もログは保持されます。完了まで待機するには --follow を追加します。

lim gradle build . --detach
lim gradle logs
lim gradle logs --follow

ツールのバージョンとシェルコマンド

同期後、lim gradle use でサンドボックス内のツールを選択し、不足しているバージョンをインストールします。同期したプロジェクトでツールを選択するには、lim gradle tools install を実行します（詳細）。ビルドではプロジェクトの gradlew を使用し、Android SDK／NDK／CMake には sdkmanager を使用します。

lim gradle tools
# Node includes npm/npx.
lim gradle use node@24 pnpm@10 yarn@4 bun@1 java@temurin-17 bundletool@1
lim gradle tools install
lim gradle run -- mise use --pin [email protected]
lim gradle run --env APP_ENV=staging -- npm run generate
lim gradle build . --env APP_ENV=staging

サンドボックスのファイルをダウンロードする

lim gradle pull-file <remote-path> [destination] --id <instance-ID> を使用します。 パスには絶対パス、または同期したプロジェクトルートからの相対パスを指定できます。 テキスト、バイナリ、Base64 の内容を含め、ファイルの転送にビルドログや実行ログを使わないでください。 ファイルを書き込むコマンドの完了を待ってください。ディレクトリは先にアーカイブし、インスタンスを削除する前にダウンロードしてください。

エミュレーターで実行する

ビルドした APK を名前付きアセットとしてアップロードし、Android インスタンスにインストールします：

lim gradle build . --upload myapp.apk
lim android create --install-asset=myapp.apk

ビルドのアップロードでは、デフォルトの TTL は 14 日です。ビルドごとに、アップロードしたアセットの有効期限がそのアップロードから 14 日後に設定されます。変更するには、Go の期間表記（例：720h。1d は無効です）を指定して --upload-ttl を渡します。

作成コマンドの出力に表示される署名付きストリーム URL は、[ライブエミュレーター](<signed-stream-url>) のような Markdown リンクにしてユーザーに共有します。ビルドを繰り返す場合は、インスタンスを作り直さず、インストール済み APK にパッチを適用してください：

lim android sync ./path/to/app-debug.apk

デバイス上でのその他の操作（タップ、入力、要素ツリー、スクリーンショット、動画、adb 経由の logcat）には、limrun-android-emulator を使用してください。

リリース AAB に署名する

デフォルトの署名方法では、ユーザーの認証情報は一切必要ありません。

lim gradle build . --sign --upload myapp.aab

初回使用時に、Limrun はアップロード用キーストアを生成し、このアプリの組織の署名キーとしてエスクローに保管して、そのキーで署名します。同じアプリであれば、その後の --sign ビルドはどのマシンや CI から実行しても同じキーを使うため、Play Store へのアップロード時も署名が一致します。キーの名前には、app.json（Expo）または app/build.gradle(.kts) から検出された Android アプリケーション ID が使われます。検出に失敗する場合や、誤ったフレーバーが選ばれた場合は、--application-id <id> を指定してください。

--sign を指定すると、デフォルトのタスクが bundleRelease になります。明示的に指定した --task のリストにバンドルタスクが含まれていない場合、ビルドは開始前に失敗します。ビルドが SUCCEEDED になれば、AAB には署名が付与されています（アップロード前にサーバーが検証します）。そのため、ユーザーから求められない限り、成果物を再検証する必要はありません。

ビルド開始前に、次のいずれかの行が表示されます。その意味を伝えてください。

• Signing with the organization's upload key for <app> (newly generated).： このアプリの初回ビルドです。キーは組織全体で使える状態になりました。
• Signing with the organization's upload key for <app> (existing).：エスクローに保管されたキーを再利用しています。これは想定どおりの動作です。

独自のアップロードキーを使用する

アプリに登録済みのアップロードキーがある場合（既存の Play リスティングがある場合）、ユーザーは代わりに自分のキーストアで署名できます。キーストアのパス、キーエイリアス、および 2 つのパスワードは、ユーザー自身のマシンで、--keystore、--key-alias、--keystore-password、--key-password フラグ、または LIM_KEYSTORE_PASSWORD と LIM_KEY_PASSWORD 環境変数を使って指定します（これらは lim gradle build --help に記載されています）。会話の中でこれらの値を尋ねたり、扱ったりしないでください。不足している値があれば、設定すべきフラグまたは変数の名前を伝えてください。4 つすべてをまとめて指定する必要があります。--save-key を追加すると、指定したキーをエスクローに保管できるため、以降のビルドではフラグを省略して、通常の --sign を使用できます。--save-key は既存のキーを上書きしません。アプリに別のキーがすでにエスクローに保管されている場合、インスタンスの作成前に失敗します。

キーストアファイル自体はユーザーのマシン上に保管してください。コミットしたり、その内容をファイルに貼り付けたりしないでください。ユーザーがエイリアスを把握していない場合は、keytool -list -keystore <file> で確認できます。

独自キーを使用する場合に認識すべきエラー文字列は次のとおりです。

• The organization already has a different upload key escrowed for <app>： --save-key の競合です。--sign を指定したビルドでは、エスクローに保管されたキーが使われます。このビルドだけ指定したキーストアで署名するには --save-key を省略するか、どちらが正しいアップロードキーかをユーザーに確認してください。
• Signing with your own key requires ... as well：独自キー用のフラグが不足しています。メッセージに不足しているフラグがすべて示されます。
• signing <field> contains an unsupported character：パスワードまたはエイリアスに ISO-8859-1 以外の文字が含まれています。keytool（-storepasswd、-keypasswd、または -changealias）を使って、その場で Latin-1 の値に変更してください。キー自体は絶対に再生成しないでください。再生成するとアップロードキーが変わってしまいます。

Play ストアへの公開

ユーザーが自分のマシンで Play の認証情報（サービスアカウントの JSON ファイルまたはアクセストークン）を設定している場合（--playstore-service-account または --playstore-access-token フラグで渡します）、ブラウザーを使わずに、署名済みのリリース AAB を直接ビルドして公開できます。会話の中でこれらの認証情報を求めないでください。

lim gradle build . --sign --upload-to-playstore --playstore-service-account sa.json --auto-version-code

--auto-version-code を指定すると、ビルド前にサーバーが Google Play から次に使用可能な versionCode を取得し、ワークスペース内のコピーに設定します（Expo プロジェクトでは app.json の expo.android.versionCode、ネイティブ Gradle プロジェクトでは従来の app/ モジュールのビルドスクリプトにある単一のリテラル versionCode）。これにより、繰り返し公開しても競合しません。このオプションを指定しない場合、または算出値や flavor ごとに分割された versionCode を使用するプロジェクトの場合（リクエスト時に拒否されます）は、以下のように versionCode を自分で管理してください。Play の認証情報がない場合、公開処理自体は実行できません。公開には Google サインインを使うブラウザーフローが必要です。アーティファクトを準備してアセットとしてアップロードし、ユーザーに引き継いでください。

lim gradle build . --sign --upload <app>-v<versionCode>.aab

ユーザーに https://console.limrun.com を開き、Secrets ページで Connect Play Console をクリックして、そのアプリのリリース権限がある Google アカウントでサインインするよう伝えてください（セッションはブラウザー内にのみ保存され、ほかの場所には保存されません）。次に Registry ページで、アップロードした AAB の Publish to Play Store をクリックし、パッケージ名（アプリケーション ID）を入力します。アプリの掲載情報は、あらかじめ Play Console に作成しておく必要があります。Google Play では、これまでに使用されたことのない versionCode が必要です。公開用ビルドでは --auto-version-code がこれを処理します。このオプションを指定しない場合は、ビルド前に app/build.gradle(.kts) の versionCode を増やしてください（Expo の場合は、app.json の expo.android.versionCode）。

--sign の処理で認識すべきエラーメッセージ：

• Cannot determine the Android application ID for signing：app.json に android.package がなく、app/build.gradle(.kts) に applicationId もないため検出できませんでした。--application-id <id> を指定してください。
• --sign produces a Play-ready signed AAB; include a bundle task：明示的に指定した --task のリストに bundle タスクがありません。bundleRelease を追加するか、--task を省略してください。
• the built AAB carries no signature：ビルド後のサーバー側チェックで、署名されていないバンドルが見つかりました。署名設定が適用されていません。ユーザーのコードの問題ではありません。再試行し、繰り返し発生する場合は報告してください。

プルリクエストの Android プレビュー

プルリクエストで繰り返しプレビューを行う場合は、パッケージ化されたAndroid preview actionを使用してください。アプリをビルドしてアップロードし、PR のプレビューコメントを更新したうえで、ビルダーをクリーンアップします。入力項目とワークフローの例については、リポジトリを参照してください。

注意点

• ビルドエラーへの対処も作業の一部です。 ビルドに失敗したら、エラー出力を読み、コードを修正して、報告する前に再ビルドしてください。
• プロジェクトの mise ファイルに、ビルドで使わないツールが含まれていることがあります。 サンドボックスで最初にビルドまたは実行すると、同期された mise ファイル内のすべての [tools] エントリーに対して mise install が実行されるため、データベースやクラウドの CLI が大量に含まれるモノレポのルート mise.toml は、処理を遅らせたり失敗させたりします。問題なく使える場合は、引き続きプロジェクトファイルを使用してください。うまくいかない場合は、その隣にビルドに必要なツール（たとえば、node や pnpm）だけを記載した mise.limrun.toml を追加してください。そのディレクトリでは、Limrun はほかの mise ファイルではなく、こちらを読み込みます。
• インスタンスの再利用は Git ワークツリーごとに行われます。 コマンドは、現在の作業ディレクトリのワークツリーから記憶されたインスタンスを特定します。特定のインスタンスを指定するには、lim gradle list で確認した --id <gradle-instance-id> を渡してください。
• Play にアップロードするたびに、versionCode を増やす必要があります。 公開ビルドでは --auto-version-code の使用を推奨します。version code がすでに存在するという理由で公開が拒否された場合は、値を増やして、再ビルドし、再公開してください。公開の RETRY でこのエラーが報告された場合、先の試行はすでに成功しています。再公開しないでください。
• アプリケーション ID の検出では、最初に見つかったコメントアウトされていない applicationId を読み取ります。 フレーバー固有の ID と動的な Gradle ロジックは対象外です。その場合は --application-id を使用してください。
• キーストアのパスワードは空ではなく、ISO-8859-1 である必要があります。 空のパスワードや Latin-1 の範囲外の文字は、ビルド開始から数分後に失敗するのではなく、リクエスト時に拒否されます。
• 同期するファイルは小さく保ち、ビルドディレクトリの外に置いてください。 ルートレベルの build/、.gradle、.kotlin と、すべての local.properties は同期されません。また、ネストされたものも含め、.gitignore ファイルが適用されます。そのほかの大きなローカル成果物を除外するには --ignore <regex> を使用し、ビルドに必要な Git の無視対象ファイルを強制的に同期するには --include <regex> を使用してください。