bm sync

設定ファイルの内容をベースマキナの環境に同期するコマンドです。同期先の環境IDの有無で挙動が変わります。

環境ID未指定: 設定ファイルの内容を開発環境に反映します（設定ファイルとデータベースの差分検出・反映）
環境ID指定: 指定した環境に、他環境のバージョンと有効化設定を同期します（環境間のデプロイ）

いずれの場合も、実行前に設定内容のバリデーションが行なわれます。

# 開発環境に反映する（ドライラン）
bm sync --dry
 
# 開発環境に反映する
bm sync
 
# 設定ファイルから削除されたアクションを開発環境で無効化して反映する
bm sync --with-disable
 
# 開発環境の状態を検証環境に同期する
bm sync <検証環境のID>
 
# 検証環境の状態を本番環境に同期する
bm sync <本番環境のID> --from <検証環境のID>
 
# 同期内容をドライランで確認する
bm sync --dry <環境ID>

オプション

オプション	デフォルト値	説明
第1引数	（省略可）	同期先の環境ID。省略した場合は開発環境への反映になる
`--config <path>`	`basemachina.config.ts`	設定ファイルのパス
`--from <environmentId>`	開発環境のID	同期元の環境ID。同期先の環境IDを指定したときのみ使用可
`--dry`	（反映する）	変更を適用せずに実行結果を確認する
`--with-disable`	（無効化しない）	設定ファイルに存在しないアクションを開発環境で無効化する。同期先の環境ID未指定時のみ使用可

--fromは同期先の環境IDを指定したときのみ、--with-disableは同期先の環境IDを指定しないとき（開発環境への反映）のみ使用できます。それ以外の組み合わせで指定するとエラーになります。

開発環境への反映（環境ID未指定）

同期先の環境IDを指定しないと、設定ファイルの内容を開発環境に反映します。

差分検出の仕組み

設定ファイルとベースマキナのデータベースの内容を、アクションの識別子（displayID）で突きあわせて比較します。

設定ファイル	データベース	結果
存在する	存在する（有効）	内容に差分がある場合は更新
存在する	存在する（開発環境で無効）	再有効化（内容に差分がある場合は併せて更新）
存在する	存在しない	作成
存在しない	存在する	何もしない（`--with-disable`指定時は開発環境で無効化）

設定ファイルに含まれないアクションは、デフォルトでは変更されません。--with-disableオプションを指定した場合のみ、設定ファイルに存在しないアクションが開発環境で無効化されます。

管理方法による挙動の違い

ベースマキナのアクションは、最後に作成・更新した場所によって「コード管理」と「Web UI管理」のいずれかに分類されます。bm syncはこの管理方法に応じて挙動を切り替えます。

データベース側の管理方法	設定ファイルに同じ識別子のアクションが存在する場合	設定ファイルに存在しない場合（`--with-disable`指定時）
コード管理	内容の差分に応じて作成・更新。差分がなければ変更なし	開発環境で無効化
Web UI管理	管理方法を「コード管理」に移行（内容に差分があればあわせて更新）	無効化対象外（引き続きWeb UIで管理される）

Web UIで作成・更新されたアクションを設定ファイルに含めてbm syncを実行すると、そのアクションの管理方法がコード管理に切り替わります。設定ファイルに含めていないWeb UI管理のアクションは、--with-disableを指定しても無効化されません。

開発環境での無効化と再有効化

--with-disableによる無効化は、アクションの有効化設定の開発環境の設定を「無効」に変更する操作です。アクション自体は削除されず、識別子（displayID）も保持されます。

一度無効化されたアクションを設定ファイルに戻して再度bm syncを実行すると、開発環境で自動的に再有効化されます。これにより、git revertや設定ファイルの巻き戻しで無効化を取り消せます。

他の環境（検証環境・本番環境など）の有効化設定は、--with-disableでは変更されません。ほかの環境へ状態を伝播させるには、同期先の環境IDを指定したbm syncを使用します。

差分の出力内容

開発環境への反映時は、以下のサマリーを出力します。--dry指定時はヘッダーが「pushすると以下の変更が適用されます」、反映時は「pushが完了しました」となります。

push が完了しました

■ コード管理のアクション
  作成: N 件
  更新: N 件
  再有効化: N 件
  開発環境で無効化: N 件
  変更なし: N 件

■ Web UI 管理のアクション
  コード管理に移行（設定変更なし）: N 件
  コード管理に移行（設定変更あり）: N 件
  無効化対象外（引き続き Web UI で管理）: N 件

「Web UI 管理のアクション」ブロックは、該当するアクションが1件もない場合は表示されません。

各ブロックの件数に対応するアクションの詳細（作成内容、差分、対象アクションの一覧）は、サマリーの下に続けて表示されます。

--with-disableを指定していない状態で無効化対象が存在する場合、サマリーの「開発環境で無効化」行には「--with-disableが指定されていないため適用されません」の注記が付きます。

他の環境への同期（環境ID指定）

同期先の環境IDを指定すると、同期元環境のバージョンと有効化設定で同期先環境を上書きします。検証環境や本番環境へのデプロイに使用します。

同期元環境は--fromで指定するか、省略した場合は開発環境になります。

同期対象

バージョンと有効化設定は同時に同期されます。

同期元の設定	同期先の設定	動作
有効	有効	バージョンを同期
有効	無効	有効化＋バージョンを同期
無効	有効	無効化＋バージョンを同期
無効	無効	バージョンを同期
任意	未設定	同期元の状態で新規作成
未設定	任意	同期しない

同期元の有効化設定が無効の場合でも、バージョンは同期先にコピーされます。これにより、後から同期先を有効化した際に、同期元と同じバージョンで動作することが保証されます。

バージョン指定との関係

アクションのバージョンには「特定のバージョン」と「常に最新」の2通りの指定方法があります。bm syncは同期元のバージョン指定をそのまま同期先にコピーします。

同期元が「特定のバージョン」の場合、同期先も同じ特定のバージョンに設定されます
同期元が「常に最新」の場合、同期先も「常に最新」に設定されます

開発環境への同期は禁止

開発環境は「設定ファイルからの反映」によって変更される起点であり、他の環境から同期する対象にはなりません。bm syncの同期先に開発環境のIDを指定するとエラーになります。

実行結果の出力

他の環境への同期時は「デプロイが完了しました」、ドライラン時は「デプロイ内容を確認します (--dry)」というヘッダーで、以下のサマリーと同期したアクションの一覧が出力されます。

デプロイが完了しました

デプロイ元環境: <同期元環境の名前>
デプロイ先環境: <同期先環境の名前>

デプロイしたアクション: N件
  <アクション名> (<識別子>):
    <同期前のバージョン> → <同期後のバージョン>

ドライラン時は「デプロイしたアクション」が「デプロイするアクション」に変わり、末尾に「※ --dry 指定のため変更は適用されていません」の注記が出力されます。

「常に最新」が指定されたアクションは、バージョン表記が常に最新と表示されます。

エラーケース

他の環境への同期では、以下のケースがエラーとして扱われます。

エラー条件	出力メッセージの例
同期元環境が見つからない	`デプロイ元環境「<環境ID>」が見つかりません`
同期先環境が見つからない	`デプロイ先環境「<環境ID>」が見つかりません`
`--from`未指定かつ開発環境が設定されていない	`デプロイ元環境が指定されていません。`--from`で指定するか、プロジェクトに開発環境を設定してください`
同期元と同期先が同じ環境	`デプロイ元環境とデプロイ先環境に同じ環境は指定できません`
同期元環境が無効化されている	`デプロイ元環境「<環境ID>」は無効化されています`
同期先環境が無効化されている	`デプロイ先環境「<環境ID>」は無効化されています`
同期先に開発環境を指定	開発環境への同期はエラーになります

実行環境の自動検出

開発環境への反映時は、実行環境（GitHub Actions、GitLab CI、ローカル端末など）を自動検出し、出力形式を切り替えます。GitHub ActionsおよびGitLab CI上では、作成アクションの詳細を<details>タグで折り畳んでPRコメントに貼り付けやすい形式で出力します。その他の環境ではプレーンテキストで出力されます。

出力形式を明示的に切り替えるオプションはありません。

readFile CI/CDの設定