ShorebirdとCodemagicの連携手順｜codemagic.yaml・APIキー移行・Codemagic CLIの使い方【2026年10月】

Shorebirdは、Flutterアプリの修正をストア審査を通さずに端末へ届けるコードプッシュのサービスです。CodemagicはFlutterに強いモバイル向けCI/CDで、ビルド・署名・ストア提出を担います。両者を組み合わせると、ストアに出すリリースと、その後のパッチ配信を同じパイプラインで回せます。この記事では、2026年10月1日時点の両社の公式ドキュメントをもとに、認証トークンの作り方、codemagic.yamlの書き方、iOS署名で使うCodemagic CLI tools、料金、つまずきやすい点を整理します。shorebird login:ci で作ったトークンは2026年9月までで使えなくなると告知されているため、以前に連携を組んだ方も確認してください。

まとめ：ShorebirdとCodemagic連携の要点

• CIの認証はShorebird ConsoleのAPIキー（sb_api_ で始まる値）を環境変数 SHOREBIRD_TOKEN に入れます。shorebird login:ci は非推奨で、発行済みトークンは2026年9月までの動作と告知されています。10月以降は止まる前提で差し替えてください。
• Codemagicではトークンを shorebird という名前のグループに登録し、codemagic.yamlでそのグループを読み込みます。
• ビルドコマンドの flutter build を shorebird release（ストア提出用）と shorebird patch（パッチ配信用）に置き換えるのが連携の中身です。
• パッチで変えられるのはDartコードだけです。ネイティブコードやアセットの変更、ネイティブ部分を持つプラグインの追加はストアリリースが必要です。
• iOSの署名は、Codemagic CLI tools（keychain・app-store-connect・xcode-project）で証明書とプロファイルを取得して行います。このツールはpipで入り、ローカルや他のCIでも動きます。

ShorebirdとCodemagicの役割分担

Shorebirdの shorebird release は flutter build の置き換えです。アプリをビルドし、コンパイル済みのDart部分をShorebirdのサーバーへ基準として登録します。Shorebirdは、生成した .aab や .ipa をストアへ提出しません。その提出を自動化するのがCodemagicの担当です。

パッチは既存のリリースに対してだけ作れます。shorebird patch はリリース時に使ったFlutterのバージョンを自動で調べて同じ版でビルドするので、リリース側でFlutterの版を固定しておくことが連携の前提になります。Shorebirdの対応プラットフォームはAndroid・iOS・macOS・Windows・Linuxですが、Codemagicの画面設定（Workflow Editor）で選べるのはAndroidとiOSだけです。

SHOREBIRD_TOKENの作成とCodemagicへの登録

releaseやpatchの作成には認証が必要です。CIでは、ログイン操作の代わりに環境変数 SHOREBIRD_TOKEN を読ませます。変数名は以前から変わっていません。変わったのは中に入れる値の作り方です。

Shorebird ConsoleでのAPIキー発行

1. Shorebird Console の Account → API Keys を開き、Create API Key を押します。
2. 名前（例：Codemagic – 自社アプリ名）を付け、有効期限を30日・90日・1年（既定）・無期限から選びます。
3. 権限を選びます。Full access はアカウントと同じ権限で、全プランで使えます。Release & Patch only はリリースとパッチの作成だけに絞った権限で、ProとBusinessプランで使えます。
4. 表示されたキーをコピーします。値は作成直後に一度しか表示されず、あとから再表示できません。

キーは sb_api_ という接頭辞で始まります。この接頭辞はGitHubのシークレットスキャンに登録されているため、公開リポジトリに誤ってコミットすると検出されます。CIに渡すキーは、アプリやメンバー、請求を操作できない Release & Patch only にしておくのが安全です。無料プランではこの権限を選べないので、Full access のキーの有効期限を短めにして回します。

Codemagicのグループ「shorebird」への登録

Codemagicでは、左メニューの Teams からチームを選び、Global Variables and Secrets タブを開きます。変数名に SHOREBIRD_TOKEN、値にAPIキーを入れ、グループ名を shorebird にして Secure にチェックを入れます。後述のcodemagic.yamlはこのグループ名を読み込むので、名前を変えた場合はYAML側も合わせます。

login:ci で作ったトークンからの移行

以前の手順では、ローカルで shorebird login:ci を実行して得た値を SHOREBIRD_TOKEN に入れていました。このコマンドは非推奨になり、Shorebirdは2026年6月16日のブログ記事で、発行済みトークンは2026年9月まで動き、その後は停止すると告知しています。実体はGoogleやMicrosoftのOAuthリフレッシュトークンを包んだもので、人間のセッションと同じ権限を持っていました。

移行はSecretの値を差し替えるだけです。上の手順でAPIキーを作り、Codemagicの SHOREBIRD_TOKEN の値を上書きして、ワークフローを1回実行します。YAMLの書き換えは要りません。古いトークンのままのCLIは、コマンドのたびに非推奨の警告をログに出していたので、2026年9月以前のビルドログに警告が残っていれば移行漏れの目印になります。

codemagic.yamlの構成（Androidのリリースとパッチ）

ここではShorebird連携をcodemagic.yamlで設定します。事前にローカルのFlutterプロジェクト直下で shorebird init を実行し、生成されたshorebird.yamlとpubspec.yamlなどの変更をコミットして、リポジトリをCodemagicに接続しておきます。

Shorebirdの公式ガイドはYAML前提で、共通の設定を definitions に置き、リリース用とパッチ用の2つのワークフローから参照する形です。

次の例は公式ガイドをもとにした構成です。実行前に署名用キーストアをCodemagicへandroid_keystoreという名前で登録し、Androidのrelease署名設定でCM_KEYSTORE_PATH・CM_KEYSTORE_PASSWORD・CM_KEY_ALIAS・CM_KEY_PASSWORDを参照させます。また、Google Playへの公開権限を持つサービスアカウントのJSONキーを、play_storeグループのGCLOUD_SERVICE_ACCOUNT_CREDENTIALSにSecretとして登録します。

definitions:
  environment:
    shared_env: &shared_env
      flutter: 3.47.5
      groups:
        - shorebird   # SHOREBIRD_TOKEN を読み込む
        - play_store  # GCLOUD_SERVICE_ACCOUNT_CREDENTIALS を読み込む
      vars:
        FLUTTER_VERSION: 3.47.5
  scripts:
    - &shorebird_install
      name: Install Shorebird
      script: |
        curl --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/shorebirdtech/install/main/install.sh -sSf | bash
        echo PATH="$HOME/.shorebird/bin:$PATH" >> $CM_ENV
    - &fetch_dependencies
      name: Fetch Dependencies
      script: |
        flutter pub get

workflows:
  release-android-workflow:
    name: Release Android
    instance_type: mac_mini_m2
    environment:
      <<: *shared_env
      android_signing:
        - android_keystore
    scripts:
      - *shorebird_install
      - *fetch_dependencies
      - name: Shorebird Release
        script: |
          shorebird release android \
            --flutter-version="$FLUTTER_VERSION"
    artifacts:
      - build/**/outputs/**/*.aab
      - build/**/outputs/**/mapping.txt
    publishing:
      google_play:
        credentials: $GCLOUD_SERVICE_ACCOUNT_CREDENTIALS
        track: internal

  patch-android-workflow:
    name: Patch Android
    instance_type: mac_mini_m2
    environment:
      <<: *shared_env
      android_signing:
        - android_keystore
    inputs:
      release_version:
        description: The release version to patch
    scripts:
      - *shorebird_install
      - *fetch_dependencies
      - name: Shorebird Patch
        script: |
          shorebird patch android \
            --release-version=${{ inputs.release_version }}

押さえるべき箇所は4つです。

• PATHの追加：Shorebirdは ~/.shorebird/bin に入ります。Codemagicでは $CM_ENV に書き込んだ変数が後続のステップへ引き継がれるので、インストール直後にPATHを追記します。
• Flutterの版の固定：--flutter-version を付けないと、shorebird release はShorebirdが対応する最新のstableでビルドするため、Shorebird側の更新でCIのFlutterの版が変わります。2026年10月1日時点のFlutterのstableは3.47.5（2026年9月18日公開）で、Shorebirdの公式ガイドの例もこの版を指定しています。ローカルとCIで版を揃える運用はFVMとは？Flutter SDKをプロジェクト単位で固定する運用とCI設定【2026年8月時点】で扱っています。
• パッチ側は --release-version：shorebird patch は --flutter-version を受け付けず、どのリリースに当てるかを指定します。inputs を使うと、ビルド開始時にCodemagicの画面から版（例：1.0.0+1）を入力できます。latest を渡すと最新のリリースが対象になります。
• マシン種別：公式ガイドの例は mac_mini_m1 のままですが、Codemagicは2024年9月1日にM1をM2へ置き換えており、mac_mini_m1 を指定したビルドはM2で動いたうえでログに非推奨のメッセージが出ます。現在の指定値は mac_mini_m2 と mac_mini_m4 で、M4とLinux・Windowsは課金を有効にしたアカウントでのみ選べます。

iOSワークフローの署名とexport_options.plist

iOSのリリースでは、App Store Connect APIキーを使って署名ファイルを取得します。掲載例のTestFlight提出には、同じAPIキーをCodemagicのチーム設定のApp Store Connect連携へ登録し、その登録名を integrations.app_store_connect に指定する準備も必要です。例の Codemagic は実際の登録名に置き換えます。Shorebirdの公式ガイドは、次の4つの変数を app_store グループにまとめる構成です。

スクリプトは、署名ファイルの取得、キーチェーンの初期化、証明書の追加、プロファイルの適用の順に並べます。以下は既存YAMLへの追加部分です。署名用アンカーは既存の definitions.scripts のリストへ、release-ios-workflowは既存の workflows 配下へ追加します。scriptsやworkflowsのキー自体を重複させず、既存のインストール・依存取得用アンカーも残します。共通設定の groups には app_store を、vars にはアプリのバンドルIDを入れた BUNDLE_ID を足しておきます。

  scripts:
    - &fetch_signing_files
      name: Fetch signing files
      script: |
        app-store-connect fetch-signing-files "$BUNDLE_ID" \
          --type IOS_APP_STORE --create \
          --issuer-id "$ISSUER_ID" \
          --key-id "$KEY_ID" \
          --private-key="$APP_STORE_CONNECT_PRIVATE_KEY"
    - &ios_initialize_keychain
      name: Initialize keychain
      script: keychain initialize
    - &add_certs_to_keychain
      name: Add certs to keychain
      script: keychain add-certificates
    - &use_profiles
      name: Use profiles
      script: |
        xcode-project use-profiles --custom-export-options={\"manageAppVersionAndBuildNumber\":false}

workflows:
  release-ios-workflow:
    name: Release iOS
    instance_type: mac_mini_m2
    integrations:
      app_store_connect: Codemagic
    environment:
      <<: *shared_env
    scripts:
      - *shorebird_install
      - *fetch_dependencies
      - *fetch_signing_files
      - *ios_initialize_keychain
      - *add_certs_to_keychain
      - *use_profiles
      - name: Shorebird Release
        script: |
          shorebird release ios \
            --flutter-version="$FLUTTER_VERSION" \
            --export-options-plist=/Users/builder/export_options.plist
    artifacts:
      - build/ios/ipa/*.ipa
    publishing:
      app_store_connect:
        auth: integration
        submit_to_testflight: true

Shorebirdの公式例には、Codemagicに事前登録した署名ファイルを使う ios_signing の指定も並んでいます。ここではCLIで証明書とプロファイルを取得する方式に揃えたため外しました。ios_signing を残す場合は、Codemagicの Code signing identities にそのバンドルID用のプロファイルを登録しておかないと、ビルドの途中で見つからないというエラーになります。

xcode-project use-profiles は、書き出し設定のファイルを既定でホームディレクトリ直下の export_options.plist に作ります。Codemagicのビルドユーザーのホームは /Users/builder なので、shorebird release ios にはそのパスを渡します。manageAppVersionAndBuildNumber を false にしているのは、Xcodeにビルド番号を書き換えさせないためです。書き換えられると、Shorebirdに登録した版とストアに届いた版がずれ、パッチが当たりません。

パッチ用ワークフローにはAndroid例と同じ inputs.release_version の定義を追加します。署名用スクリプトを再利用し、最後のビルド手順を shorebird patch ios --release-version=${{ inputs.release_version }} に変えて --export-options-plist を同じく渡します。プロビジョニングプロファイルの種類と失効の扱いはプロビジョニングプロファイルとは｜iOS署名の仕組み・4種類・作成・更新・エラー対処が詳しいです。

Codemagic CLI toolsのコマンドと単体での使い方

上のiOSスクリプトで使った keychain・app-store-connect・xcode-project は、Codemagicが公開しているPythonパッケージ codemagic-cli-tools のコマンドです。Codemagicのビルドマシンには入っていますが、Codemagic専用ではなく、ローカルのMacやGitHub Actionsでも pip で入れて使えます。2026年10月1日時点のPyPI最新版は0.69.0（2026年7月15日公開）で、Python 3.8以上が必要です。

python3 -m pip install codemagic-cli-tools
app-store-connect --version      # app-store-connect 0.69.0
keychain --help

インストールすると次の10個のコマンドが入ります。0.69.0を実際に入れ、パッケージが登録するコマンドと --help の内容で確認しました。READMEの一覧には firebase-app-distribution が載っていないので注意してください。

認証情報はオプションで渡すか、環境変数で渡します。app-store-connect は APP_STORE_CONNECT_ISSUER_ID・APP_STORE_CONNECT_KEY_IDENTIFIER・APP_STORE_CONNECT_PRIVATE_KEY を読み、google-play は GOOGLE_PLAY_SERVICE_ACCOUNT_CREDENTIALS を読みます。秘密鍵を平文で書きたくないときは、値を @env:変数名 や @file:パス の形で渡せます。p8ファイルを ~/.appstoreconnect/private_keys/AuthKey_キーID.p8 に置いておけば、--private-key を省いても見つけてくれます。

Shorebirdと組み合わせるときに役立つのが、ビルド番号の取得です。Shorebirdのリリースは版ごとに一意である必要があるため、ストアの最新番号に1を足す方法は採番の出発点になります。ただし、同時実行中のジョブやストア未提出のShorebirdリリースとは重複し得るため、リリース処理の直列化や一意な採番も必要です。

app-store-connect get-latest-testflight-build-number 1234567890
google-play get-latest-build-number --package-name com.example.app --tracks internal

ローカルのMacで keychain initialize を実行すると、署名用の一時キーチェーンが既定のキーチェーンになります。作業後は keychain use-login でログインキーチェーンへ戻さないと、他のアプリの認証で問題が出ます。GitHub Actionsやfastlaneで同じ処理を組む場合の比較材料としては、fastlaneとは？iOS・Androidのビルドと配信を自動化する使い方【2.240対応】も参照してください。

Workflow EditorとYAMLの選び分け

ここは両社のドキュメントが食い違っています。Shorebirdのガイドは「Workflow Editor はビルドコマンドを変えられないため非対応」と書いたままです。一方、Codemagicは2026年4月1日更新のドキュメントで、Flutter向けWorkflow Editorに Publish updates to user devices using Shorebird という項目から、画面上でReleaseかPatchを選択できると説明しています。

Flutterアプリを1本、AndroidとiOSで出すだけならWorkflow Editorで足ります。flavorごとに複数のアプリを出す、ステージング用トラックへパッチを出してから昇格させる、PRごとに検証ビルドを回す、といった運用があるならYAMLを選びます。Workflow Editorでパッチを作るときは、Codemagicのドキュメントどおり、リリースを作ったときと同じXcodeの版を指定してください。版が違うと「ネイティブの変更を含む」という警告が出ます。

Shorebirdパッチの変更可能範囲と制約

Shorebirdのパッチで変更できるのはDartコードです。パッチ作成時にCLIがリリース時の成果物と比べ、ネイティブコードやアセットの差分を見つけると警告を出し、既定ではアップロードを止めます。

• 直せる：Dartのロジック・画面・文言の修正、純粋なDartパッケージの追加や更新
• 直せない：Kotlin・Java・Swift・Objective-Cのコード、android/ や ios/ のビルド設定、pubspec.yaml で宣言する画像やフォントの追加・削除
• 注意が要る：camera や path_provider のようにネイティブ部分を持つパッケージは、ストアに出したリリースに既に含まれている場合だけ使えます。パッチで新たに足すとビルドは通りますが、端末ではネイティブ部分が無いためクラッシュします。

CIの中ではCLIが非対話モードで動くため、ネイティブの差分があると shorebird patch はエラーで止まり、必要なフラグ名（--allow-native-diffs）を表示します。公式はこのフラグを日常的に使うことを強く勧めていません。フラグで通したくなったら、その修正はストアリリースで出すべきものだと判断してください。

iOSでは、変更したDartコードはインタープリターで動きます。多くの場合は体感差がありませんが、画像処理や大量データの処理を書き換えると遅くなることがあります。iOSシミュレーターではパッチを試せないため、確認には実機が要ります。Google Playについても、Shorebirdはポリシーにある「仮想マシンやインタープリターで動くコード」の例外に沿っていると説明しています。

パッチ配信の運用：ステージング・昇格・ロールバック

パッチはいきなり全端末に出さず、トラックを分けて段階的に出せます。--track を省くと既定の stable に出るため、CIのパッチ用ワークフローでは先に staging へ出す形にしておくと事故を減らせます。

shorebird patch android --release-version=1.0.0+1 --track=staging
shorebird patches promote --release-version 1.0.0+1 --patch-number 1
shorebird patches rollback --release-version 1.0.0+1 --patch-number 1

端末をstaging側に参加させるには、アプリに package:shorebird_code_push を入れ、shorebird.yaml で auto_update: false にしてトラックを指定する実装が要ります。個別のパッチは削除できず、配信を止めるときは rollback を使います。ロールバックは端末からパッチを外す操作で、後から rollforward で戻せます。

パッチ数に上限はありませんが、Shorebirdはネイティブやアセットの変更が出たときや月1回程度など、定期的にストアリリースを出すことを勧めています。新規ユーザーはストア版を入れてから初回起動後にパッチを受け取るため、元のリリースが古いほど初回のダウンロードが大きくなるからです。PRごとの検証には、アップロードせずにビルドだけ確かめる --dry-run（-n）を付けたジョブが使えます。

料金：Shorebirdのパッチインストール数とCodemagicのビルド分数

課金の単位が両者で違います。Shorebirdはパッチが端末に入った回数、Codemagicはビルドマシンの稼働分数です。

Codemagicの月500分の無料枠は個人アカウントだけで、チームで使う場合は付きません。チームは同時実行数を1つ増やすごとに月$49がかかります。Shorebirdはアプリ数とリリース数が無制限で、Release & Patch only のAPIキーやユーザー権限の細分化はPro以上の機能です。料金は変わることがあるため、契約前にShorebirdの料金ページとCodemagicの料金ドキュメントで確認してください。

連携でつまずきやすいエラーと確認点

• 2026年10月以降に認証で落ちる：SHOREBIRD_TOKEN に login:ci 由来の値が残っている可能性があります。APIキーを発行して値を差し替えます。
• shorebird: command not found：$CM_ENV へのPATH追記が抜けているか、インストールより前のステップで呼んでいます。
• パッチでネイティブ差分の警告が出る：リリース時とFlutter・Xcodeの版が違うか、実際にネイティブ側を変えています。リリース時の版に揃え、それでも出るならストアリリースに切り替えます。
• iOSでパッチが当たらない：原因の一つは、ストアに届いたビルド番号とShorebirdに登録した版の不一致です。manageAppVersionAndBuildNumber が false になっているかを確認します。
• リリースの版番号が重なる：Codemagicのドキュメントは、リリースごとに一意の版を付けるよう求めています。get-latest-build-number 系のコマンドで番号を上げてからビルドします。

AndroidとiOSのどちらもネイティブ機能の追加が頻繁なアプリや、週に何度もストアリリースを出しているチームでは、Shorebirdを入れても使える場面が限られます。導入の効果が大きいのは、UIや業務ロジックの不具合を審査待ちなしで直したい、Dart中心のアプリです。

よくある質問

Shorebird CIとは何ですか？今も使えますか？

Shorebird CIは、Shorebirdがコードプッシュとは別に提供していたCIサービスです。2026年8月8日に廃止されました。移行先として案内されているREADMEでは、モノレポのパッケージ構成からGitHub Actionsのワークフローを生成する shorebird_ci というDartパッケージが説明されています。Shorebirdのリリースやパッチを自動化するなら、この記事のCodemagicか、GitHub Actionsの公式手順を使います。

codemagic.yamlはどこに置けばよいですか？

リポジトリのルートに、codemagic.yaml という名前で置いてコミットします。Codemagicのドキュメントはファイル名と置き場所をこの形に限っているため、拡張子を .yml にしたり、Flutterプロジェクトのサブディレクトリに置いたりすると読み込まれません。Flutterプロジェクトがサブディレクトリにある場合は、YAMLはルートに置いたまま、スクリプトの中で cd してから shorebird release を実行します。

Codemagic CLI toolsはCodemagic以外で使えますか？

使えます。READMEは「Codemagic以外の仮想環境やローカルでも使える」と明記しており、python3 -m pip install codemagic-cli-tools で入ります。Codemagic自身もGitHub ActionsからApp Store Connectへ提出する手順をブログで公開しています。App Store Connectの認証は APP_STORE_CONNECT_ISSUER_ID などの環境変数か、コマンドのオプションで渡します。Windows上でiOSアプリの提出まで回す構成はWindowsでiOSアプリを開発する方法｜Mac不要でビルドと提出を回す4経路で扱っています。

パッチはいつユーザーの端末に反映されますか？

既定では、アプリの起動時にバックグラウンドでパッチを確認・取得し、次にアプリのプロセスが起動し直したときに適用します。UIの表示は止まりません。更新の確認・取得を任意のタイミングで行う場合は package:shorebird_code_push を使います。ただし、取得済みパッチの適用にはアプリのプロセスの再起動が必要です。

ShorebirdはApp Storeの審査で問題になりませんか？

Shorebirdは、iOSではDartのインタープリターでパッチを動かすことで、FAQで引用するAppleの規約3.3.1(b)項の「ダウンロードできるのはインタープリターで動くコードに限る」条件に合わせていると説明しています。ただし同じ条項は、アプリの主目的を変える更新や、署名・サンドボックスを回避する更新を認めていません。機能を大きく変える修正はパッチで出さず、ストアの審査を通してください。

関連記事

• fastlaneとは？iOS・Androidのビルドと配信を自動化する使い方【2.240対応】
• GitHub Actionsでfastlaneを動かすiOSリリース自動化｜設定とCI固有エラー対処
• FVMとは？Flutter SDKをプロジェクト単位で固定する運用とCI設定【2026年8月時点】
• プロビジョニングプロファイルとは｜iOS署名の仕組み・4種類・作成・更新・エラー対処
• Firebase App Distributionとは｜配信物の分岐とテスター名簿・CI組み込みの設計【2026年8月時点】