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