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 | （無効化しない） | 無効化対象のアクションを反映する（同期先の指定により挙動が変わる。下記参照） |
--fromは同期先の環境IDを指定したときのみ使用できます。同期先の環境IDを指定せず--fromを指定するとエラーになります。
--with-disableの挙動は同期先の環境IDの有無で変わります。
| 同期先の環境ID | --with-disableの挙動 |
|---|---|
| 未指定 | 設定ファイルに存在しないアクションを開発環境で無効化する |
| 指定 | 同期元で無効化されているアクションも同期先に反映する（同期先で無効化された状態で同期する） |
開発環境への反映（環境ID未指定）
同期先の環境IDを指定しないと、設定ファイルの内容を開発環境に反映します。
差分検出の仕組み
設定ファイルとベースマキナ上の設定を、アクションの識別子で突きあわせて比較します。
| 設定ファイル | ベースマキナ上の設定 | 結果 |
|---|---|---|
| 存在する | 存在する（有効） | 内容に差分がある場合は更新 |
| 存在する | 存在する（開発環境で無効） | 再有効化（内容に差分がある場合は併せて更新） |
| 存在する | 存在しない | 作成 |
| 存在しない | 存在する | 何もしない（--with-disable指定時は開発環境で無効化） |
設定ファイルに含まれないアクションは、デフォルトでは変更されません。--with-disableオプションを指定した場合のみ、設定ファイルに存在しないアクションが開発環境で無効化されます。
管理方法による挙動の違い
ベースマキナのアクションは、最後に作成・更新した場所によって「コード管理」と「Web管理」のいずれかに分類されます。bm syncはこの管理方法に応じて挙動を切り替えます。
| ベースマキナ上の管理方法 | 設定ファイルに同じ識別子のアクションが存在する場合 | 設定ファイルに存在しない場合（--with-disable指定時） |
|---|---|---|
| コード管理 | 内容の差分に応じて作成・更新。差分がなければ変更なし | 開発環境で無効化 |
| Web管理 | 管理方法を「コード管理」に移行（内容に差分があればあわせて更新） | 無効化をスキップ（引き続きWebで管理される） |
Webで作成・更新されたアクションを設定ファイルに含めてbm syncを実行すると、そのアクションの管理方法がコード管理に切り替わります。設定ファイルに含めていないWeb管理のアクションは、--with-disableを指定しても無効化されません。
設定ファイルにまだ含まれていないWeb管理のアクションをリポジトリに取り込みたい場合は、bm pullを使用してください。
開発環境での無効化と再有効化
--with-disableによる無効化は、アクションの有効化設定の開発環境の設定を「無効」に変更する操作です。アクション自体は削除されず、識別子も保持されます。
一度無効化されたアクションを設定ファイルに戻して再度bm syncを実行すると、開発環境で自動的に再有効化されます。これにより、git revertや設定ファイルの巻き戻しで無効化を取り消せます。
他の環境（検証環境・本番環境など）の有効化設定は、--with-disableでは変更されません。ほかの環境へ状態を伝播させるには、同期先の環境IDを指定したbm syncを使用します。
差分の出力内容
開発環境への反映時は、以下のサマリーを出力します。ヘッダーは、--dry指定時が## bm sync 実行後、以下の変更が適用されます、反映時が## bm sync が完了しましたです。
## bm sync 実行後、以下の変更が適用されます
### コード管理のアクション
- 作成: N 件
- 更新: N 件
- 再有効化: N 件
- 開発環境で無効化: N 件
- 変更なし: N 件
### Web 管理のアクション
- コード管理に移行（変更なし）: N 件
- コード管理に移行（変更あり）: N 件
- 無効化をスキップ（Web 管理）: N 件
<details><summary>作成 (1 件)</summary>
- ユーザー一覧 (list-users)
</details>0件の項目は行自体が省略されます。### Web 管理のアクションブロックも、該当するアクションが1件もない場合は表示されません。すべての項目が0件の場合は、本文に変更はありませんと表示されます。
各ブロックの件数に対応するアクションの詳細（作成内容、差分、対象アクションの一覧）は、サマリーの下に続けて表示されます。GitHub ActionsおよびGitLab CI上では<details>タグで折り畳み可能なMarkdownとして表示され、その他の環境では作成 (N 件):のような見出しと本文のプレーンテキストで表示されます。
--with-disableを指定していない状態で無効化対象が存在する場合、以下の注記が表示されます。この場合も対象一覧は表示されますが、実際の無効化は適用されません。
> [!NOTE]
> `--with-disable` が指定されていないため、無効化は適用されません。ドライラン時は、末尾に以下の注記が表示されます。
> [!NOTE]
> `--dry` 指定のため、変更は適用されていません他の環境への同期（環境ID指定）
同期先の環境IDを指定すると、同期元環境のバージョンと有効化設定で同期先環境を上書きします。検証環境や本番環境への同期に使用します。
同期元環境は--fromで指定するか、省略した場合は開発環境になります。
同期対象
バージョンと有効化設定は同時に同期されます。
| 同期元の設定 | 同期先の設定 | 動作 |
|---|---|---|
| 有効 | 有効 | バージョンを同期 |
| 有効 | 無効 | 有効化＋バージョンを同期 |
| 有効 | 未設定 | 有効化＋バージョンを同期 |
| 無効 | 有効 | --with-disable指定時のみ無効化＋バージョンを同期。未指定時は有効状態を維持してバージョンのみ同期 |
| 無効 | 無効 | バージョンを同期 |
| 無効 | 未設定 | --with-disable指定時のみ無効状態で同期。未指定時は同期しない |
| 未設定 | 任意 | 同期しない |
同期元の有効化設定が無効の場合でも、同期対象になったアクションのバージョンは同期先にコピーされます。これにより、後から同期先を有効化した際に、同期元と同じバージョンで動作することが保証されます。
バージョン指定との関係
アクションのバージョンには「特定のバージョン」と「常に最新」の2通りの指定方法があります。環境IDを指定したbm syncでは、同期先のバージョン指定によって挙動が変わります。
- 同期先が「常に最新」の場合、同期先のバージョン指定は「常に最新」のまま維持されます
- 同期先が「特定のバージョン」または未設定の場合、同期元が「特定のバージョン」なら同じバージョンに設定されます
- 同期先が「特定のバージョン」または未設定の場合、同期元が「常に最新」なら同期時点の最新バージョンに設定されます
開発環境への同期は禁止
開発環境は「設定ファイルからの反映」によって変更される起点であり、他の環境から同期する対象にはなりません。bm syncの同期先に開発環境のIDを指定するとエラーになります。
実行結果の出力
他の環境への同期時は、同期内容をセクション別に分類したサマリーが出力されます。ヘッダーは、--dry指定時が## bm sync 実行後、以下の変更が同期されます、反映時が## bm sync が完了しましたです。変化の種類に応じて「バージョン変更」「有効化」「無効化」の3つのセクションに分類されます。
## bm sync 実行後、以下の変更が同期されます
同期元環境: <同期元環境の名前>
同期先環境: <同期先環境の名前>
### 同期内容
- バージョン変更: N 件
- 有効化: N 件
- 無効化: N 件
<details><summary>バージョン変更 (1 件)</summary>
- ユーザー一覧 (list-users)
- v1 → v2
</details>
<details><summary>有効化 (1 件)</summary>
- 新規アクション (new-action): 無効 → 有効
</details>- 同期元と同期先の有効化設定が同じ（両方有効、または両方無効）場合はバージョン変更に分類されます。
- 同期元のみ有効の場合は有効化、同期先のみ有効の場合は無効化に分類されます。
- 同期先に未設定のアクションは、同期先の初期状態を「無効」として扱うため、同期元が有効な場合は有効化に分類されます。「追加」というカテゴリは表示されません。
- 同期対象がない場合は、本文に
変更はありませんと表示されます。 - 0件の項目は行自体が省略されます。
- ドライラン時は末尾に「
--dry指定のため、変更は適用されていません」の注記が表示されます。 - 「常に最新」が指定されたアクションは、同期元のバージョン表記が
常に最新と表示されます。
エラーケース
他の環境への同期では、以下のケースがエラーとして扱われます。
| エラー条件 | 出力メッセージの例 |
|---|---|
| 同期元環境が見つからない | 同期元環境「<環境ID>」が見つかりません |
| 同期先環境が見つからない | 同期先環境「<環境ID>」が見つかりません |
--from未指定かつ開発環境が設定されていない | 同期元環境が指定されていません。`--from` で指定するか、プロジェクトに開発環境を設定してください |
| 同期元と同期先が同じ環境 | 同期元環境と同期先環境に同じ環境は指定できません |
| 同期元環境が無効化されている | 同期元環境「<環境ID>」は無効化されています |
| 同期先環境が無効化されている | 同期先環境「<環境ID>」は無効化されています |
| 同期先に開発環境を指定 | 開発環境への同期はサポートされていません。環境IDを指定せずに `bm sync` を使用してください |
実行環境の自動検出
bm syncは実行環境（GitHub Actions、GitLab CI、ローカル端末など）を自動検出し、出力形式を切り替えます。GitHub ActionsおよびGitLab CI上では、変更の詳細を<details>タグで折り畳んでPRコメントに貼り付けやすい形式で出力します。その他の環境ではプレーンテキストで出力されます。
出力形式を明示的に切り替えるオプションはありません。