想定読者

Microsoft Fabric や Power BI でデータ基盤 / BI レポートを開発しているエンジニア・データエンジニア

「データ基盤開発を Git 管理したい」「データ基盤開発に PR レビューフローを導入したい」と考えている方

Fabric Git 統合（Azure DevOps / GitHub）の運用イメージを掴みたい方

シリーズ過去回:

第 1 回土台編 — データ基盤開発を爆速化させた構成

第 2 回 Fabric MCP Server と PowerBI Modeling MCP Server の使い分け

第 3 回 Power BIレポートの自動生成

TL;DR

.pbip(Power BI Project) + Fabric Git 統合 により、Power BI レポートとデータ基盤を ソフトウェア開発と同じ Git ベースのワークフロー（Issue → ブランチ → PR → マージ） で運用できる
Issue 駆動の 1 周ループ: Issue 起票 → feature ブランチ → 編集 → PR レビュー → main マージ → updateFromGit で workspace 反映 → Done
開発者のインタフェースは主に Claude Code。複数ツール（git / 2 つの MCP Server / Fabric CLI / Azure CLI / Boards）への呼び出しは Claude Code が裏で組み合わせる
Workspace ↔ Git ↔ ローカルクローンの 3 拠点同期 で、Notebook も Semantic Model も .pbip Report も双方向に同期できる
.pbip のテキスト差分 で BI レポートも git diff / PR レビュー対象になる。Issue / PR / commit が自動で相互リンクされ、半年後でも変更の経緯と意図を辿れる
落とし穴の「Uncommitted/Modified」現象は、Service が JSON を 4-space indent で自動整形すること による whitespace の差分で実害ゼロ。Conflict が出ても「受信した変更を受け入れる」一択
完全自動化（ポータル UI クリック不要 + commitToGit API）の話は次回（第 5 回）に続く

1. なぜ Git 管理するのか

1.1 `.pbix` でBIを開発するときの課題

従来の Power BI 開発（.pbix 形式）には、ソフトウェア開発の常識からすると不便な制約が多くありました。

バイナリで diff が取れない: .pbix は内部に圧縮された JSON / バイナリの混合形式で、Git に置いても「全体差分」しか分からない。1 つのビジュアル変更でも丸ごと差し替えに見える
同時編集が不可能: 編集ロック方式のため、複数人が同じレポートを並行で触ると マージ不能。やむなく「ファイル名_v3.pbix」のような Excel 的バージョン管理に陥る
レビューは口頭 / 画面共有頼み: 差分が読めないので「ここをこう変えました」と画面で説明するしかない
履歴消失リスク: ローカル PC やチームの共有フォルダで管理しているとファイル破損 / 上書きで履歴ごと飛ぶ

結果として、データ基盤 / BI の領域は 「ソフトウェア開発で当たり前の Git ベースのワークフロー」から長く取り残されてきました。

1.2 `.pbip` + Fabric Git 統合で何が変わったか

Power BI Desktop が .pbip（Power BI Project）形式を提供し、Microsoft Fabric が Azure DevOps / GitHub との Git 統合をサポートするようになったことで、状況が大きく変わりました。

.pbip は JSON テキスト: ページ・ビジュアル・テーマがすべて構造化された JSON ファイル群として展開される（第 3 回参照）
テキスト差分が読める: git diff で「Page 1 のタイトル textbox の値が変わった」が一目で分かる
Fabric Git 統合: Fabric ワークスペース全体（Notebook・Semantic Model・.pbip Report・Lakehouse）が Azure DevOps の 1 リポジトリと双方向同期する
PR レビューが組める: Git ベースなので feature ブランチ → Pull Request → main マージ → Fabric workspace 反映、というフローが組める

1.3 Before / After 比較

観点	Before（`.pbix` での開発）	After（`.pbip` + Fabric Git）
履歴管理	ファイル名のバージョン（`_v3.pbix`）/ チーム共有フォルダ	Git の commit 履歴
差分の可視化	不可（バイナリ）	`git diff` でテキスト差分
並行開発	ロック方式 / マージ不能	feature ブランチ / PR でマージ
コードレビュー	画面共有 / 口頭説明	PR コメント / GitHub-style レビュー
障害復旧	ローカル PC / 共有フォルダの破損リスク	Git リモートに常時バックアップ
監査ログ	「誰がいつ何を変えたか」追跡不能	commit メッセージ / Issue リンクで追跡可能

1.4 ソフトウェア開発の標準フローに乗せる意義

.pbix 時代の課題は 個々の不便さの集合ではなく、Power BI 開発が "孤立した職人作業" に押し込められていたことそのもの でした。

Fabric の Git 統合は、データ基盤・BI 開発を 「Issue 起点で feature ブランチを切り、PR レビューを通して main にマージする」というソフトウェア開発の標準フロー に乗せ直します。一度このワークフローに乗ってしまえば、過去 20 年のソフトウェア開発で培われた知見（コードレビュー文化・Issue トラッキング・CI 的な品質ゲート）がそのまま流入してきます。

次章では、その「標準フロー」がデータ基盤開発でどう回っているか、実際の開発プロセス全体像を示します。

2. 開発プロセス全体像 — Issue 駆動の開発フロー

2.1 1 周のループ

データ基盤の改修・BI ページ追加・Semantic Model のメジャー修正などの単位タスクは、Issue 1 つに紐付いた以下のループで 1 周します。

各ステップを表に整理すると次のとおりです。

Step	アクター	内容	使うツール
1	開発者	Issue 起票（タスク内容・受け入れ条件を記述）	Azure DevOps Boards
2	開発者	feature ブランチ作成	git CLI
3	開発者	Notebook / SM / `.pbip` の編集	VS Code + Claude Code + 2 MCP Server
4	git	commit	git CLI
5	git	push	git CLI
6	開発者	Pull Request 作成	Azure DevOps
7	レビュアー	PR レビュー / マージ	Azure DevOps
8	開発者	Fabric ポータル「すべて更新」	Fabric ポータル UI
9	Fabric	`updateFromGit` で workspace に差分反映	Fabric REST API
10	開発者	動作確認	Fabric workspace
11	開発者	Issue を Done に	Azure DevOps Boards

2.2 開発者の主要なインタフェース = Claude Code

シーケンス図上は 5 つのアクター（Boards / ローカル / Remote / Fabric）が登場しますが、開発者が実際に手を動かす場所は VS Code 上の Claude Code チャットに集約されます。

「この内容で Issue を立てて」「feature ブランチで Notebook を修正して」「PR を作って」と自然言語で指示するだけ
Claude Code が Fabric MCP / Power BI Modeling MCP / fab CLI / git CLI / Azure CLI を裏で組み合わせて実行
開発者が直接 UI / ターミナルを触るのは Step 8（「すべて更新」クリック）と Step 10（動作確認）だけ

「git コマンド + Azure DevOps の Web UI + Fabric ポータル + Power BI Desktop」と複数ツールを横断する印象を持たれがちですが、実際は VS Code を開いて Claude Code に話しかけるだけ で 9 割の作業が完結します。

2.3 役割分担（1 人運用 + Claude Code の場合）

このフローを「1 人運用 + Claude Code」で回す場合、各ツールの役割は以下のように分担されます。

ツール	担当
Claude Code（VS Code 拡張）	エージェントの司令塔。MCP / CLI を呼び出して編集を実行
Fabric MCP Server（第 2 回参照）	Lakehouse / Notebook / アイテム管理
Power BI Modeling MCP（第 2 回参照）	Semantic Model 操作（メジャー編集 / Deploy）
Fabric CLI	Notebook / Report の import / export
git CLI	ローカルクローンの commit / push
Azure DevOps（Boards / Repos / PR）	Issue 管理 / リポジトリ / レビューフロー
Fabric ポータル UI	「すべて更新」（`updateFromGit`）/ 動作確認

人間のレビュアーが目を入れるのは Step 7 の PR レビュー段階のみで、Step 3〜5 の編集・commit・push は Claude Code 側に任せられます。1 人運用の場合は「自分の書いた PR を一晩おいて翌朝レビューする」というセルフレビューになります。

3. Fabric Git 統合の構成 — 3 拠点同期

3.1 全体構成図

Fabric Git 統合では Fabric Workspace ↔ Azure DevOps Git ↔ ローカルクローン の 3 拠点が同期します。

各拠点の役割:

拠点	役割	同期手段
Fabric Workspace	実行環境（Notebook ジョブ / SM クエリ / Report 表示）	`updateFromGit` で Git の最新を取り込み、`commitToGit` で変更を書き戻し
Azure DevOps Git	バージョン管理 / コラボレーション拠点	`git push` / `git pull` でローカルクローンと同期
ローカルクローン	横断検索 / `git diff` / `grep` / 保険的バックアップ	git CLI で remote と同期

3.2 同期対象アイテムと除外項目

Fabric Git 統合の同期対象は アイテムの定義（構造） に限定されます。実データや運用設定は同期されません。

アイテム種別	同期	ローカルでの実体
Notebook	⭕	`<NB 名>.Notebook/notebook-content.py`
Semantic Model	⭕	`<SM 名>.SemanticModel/` 配下の TMDL
Power BI Report（`.pbip`）	⭕	`<Report 名>.Report/definition/...` 配下の JSON
Lakehouse	⭕（定義のみ）	`<LH 名>.Lakehouse/`（テーブル定義のみ）
Data Pipeline	⭕	Pipeline 定義 JSON
Lakehouse 実データ（Parquet）	❌	OneLake 上の Delta Lake に格納（同期対象外）
ジョブ実行履歴・ログ	❌	Fabric 側の運用情報
アクセス権 / ロール割り当て	❌	workspace 側設定

README.md や docs/ 等の 非 Fabric アイテムはリポジトリに置いても workspace から無視されます。これは「人間が読むためのドキュメント / 補助スクリプト / テストデータをリポに置いても workspace を汚染しない」というメリットとして使えます。

3.3 ローカルクローンの位置付け

ローカルクローンは 保険的位置付け + PR ベース編集の起点 の 2 つの役割を持ちます。

保険: Azure DevOps の Web UI が見られない時でも git log / git show で過去履歴が追える
横断検索: 複数 workspace のローカルクローンを跨いで grep でき、過去変更の探索に強い
PR ベース編集の起点: Desktop で .pbip を直接編集 → ローカルで commit → push → PR、という流れの起点

Claude Code 経由の編集では、ローカルクローンを起点にしなくても fab export で workspace から取得 → 修正 → fab import で書き戻し という直接ルートも取れます（第 5 回参照）。使い分けの目安は次のとおり。

シナリオ	推奨ルート
Desktop で `.pbip` 直接編集 / PR レビュー文化 / 複数人開発	ローカルクローン起点
Claude Code で完結 / 1 人運用 / スピード重視	`fab` CLI 直接ルート（第 5 回）

4. Git → workspace の同期実例（updateFromGit）

4.1 ポータル「すべて更新」= `updateFromGit` API

Fabric ポータルの workspace 画面上部「ソース管理」を開くと、右側にパネルが展開します。このパネルが Git 統合の操作中心です。

パネル要素	方向	対応する API
「変更」タブ	workspace → Git（outgoing）	`commitToGit`（次回詳述）
「更新情報」タブ	Git → workspace（incoming）	`updateFromGit`
パネル右上の更新アイコン	—	ステータス再取得（実際の同期は実行しない）
「更新情報」タブ右下「すべて更新」	Git → workspace	`updateFromGit` 実行
「変更」タブ右下「コミット」	workspace → Git	`commitToGit` 実行

ポータル UI には「updateFromGit」という文字列は出てきません。代わりに 「すべて更新」ボタンとして実装されているのが特徴です。

アイテム一覧の Git 状態カラムは 4 種類:

状態	意味
Synced	workspace = Git
Update Required	Git に未取り込みの変更あり
Uncommitted	workspace 側に Git 未反映の変更あり
Conflict	両方向に変更があり auto-merge できない

4.2 同期フローのシーケンス

git push → ポータル「すべて更新」 → workspace 反映の流れを図示します。

updateFromGit は LRO（Long Running Operation）扱いですが、1〜2 アイテムの軽量更新なら数秒で完了します。

4.3 Notebook の編集を Git 経由でデプロイする

<NB 名>.Notebook/notebook-content.py の最初のコードセル先頭にコメントを 1 行追加する例:

  # CELL ********************

+ # 検証マーカー
  import os
  LOG = "/lakehouse/default/Files/logs/sample.log"

git add NB_sample.Notebook/notebook-content.py
git commit -m "Add verification marker comment to NB_sample"
git push origin main

Fabric ポータルで「ソース管理」 → 「すべて更新」をクリックすると、

アイテム一覧の NB_sample の Git 状態が Update Required → Synced に変化
workspace 上で Notebook を開くと、1 行目に追加したコメントが反映されている

→ Notebook の Git sync 経由デプロイは正常動作 と確認。

4.4 `.pbip` Report の編集を Git 経由でデプロイする

本命検証は .pbip Report です。第 3 回で扱った .pbip のテキスト構造のメリットがここで効きます。

Page 1 のタイトル textbox の表示テキストを変える例:

  "textRuns": [{
-   "value": "売上ダッシュボード",
+   "value": "売上ダッシュボード (Git sync 検証)",
    "textStyle": { "fontWeight": "bold", "fontSize": "22pt" }
  }]

ファイルパス（一般形）:

<Report 名>.Report/definition/pages/<page-id>/visuals/<visual-id>/visual.json

この 1 ファイルだけ編集して git push、ポータルで「すべて更新」。

workspace の Report を開くと Page 1 タイトルが新しい文字列に更新されている
レンダリング崩れ / 他ビジュアルへの影響なし

→ .pbip Report も updateFromGit でデプロイ可能 と確認。これがこの記事の主要な結論の 1 つです。

「Page 1 のタイトル文字列を変えたい」という最小の修正が 1 つの JSON ファイルの 1 ファイル差分 で表現でき、Git でも Fabric でもその粒度のまま同期される。これは .pbix（バイナリ）では絶対にできない芸当です。

4.5 非 Fabric ファイル（README / docs/）の扱い

リポジトリルートの README.md に行を追加して git push した場合:

「更新情報」タブには 何も検出されない
Fabric Git 統合は Fabric アイテム以外のファイルを完全に無視する

これは docs/ ディレクトリや補助スクリプト・テストデータをリポジトリに同居させても workspace を汚染しないことを意味します。「人が読むドキュメント」「Python ヘルパースクリプト」「補助テンプレート」をリポ内に置くデータ基盤プロジェクトでは、この特性が運用に効きます。

5. 履歴管理とコードレビューの実践

5.1 Issue 番号付き commit 規律

commit メッセージに Boards Issue 番号 を含めるのが基本ルールです。Azure DevOps は commit メッセージ / PR description に AB#NN の形式で Work Item を引用すると、自動でリンクを張ってくれます。

commit メッセージのスタイル例:

AB#42 fact_sales に売上総利益メジャーを追加

- SM_sales: gross_profit メジャー定義 (DAX)
- Page 5「収益サマリ」: 棒グラフ追加 + メジャーをバインド
- formatString は #,0 統一に従う

ポイント:

subject 行（1 行目）は 72 文字以内 で「Issue 番号 + 何をしたか」を簡潔に
body（空行を挟んで以降）は何を / なぜ / どこに影響したか を箇条書きで詳細化
単に「メジャーを追加」だけだと半年後の自分が見て何をしたか不明になる

アンチパターン:

メジャーを追加

これだと git log で見ても「何のメジャーを」「なぜ」「どこに」が一切分からず、Issue 番号も無いので逆引きもできません。徹底するだけで git log の検索性が劇的に上がります。

5.2 `.pbip` の diff が読める

.pbip がテキストである恩恵は git diff で BI レポートの変更を読める ことに尽きます。

ビジュアルのタイトル文字列を変えた場合:

   "textRuns": [{
-    "value": "売上ダッシュボード",
+    "value": "売上ダッシュボード（2026 年版）",
     "textStyle": {
       "fontWeight": "bold",
       "fontSize": "22pt"
     }
   }]

メジャー（TMDL）を追加した場合:

+ measure gross_profit =
+     SUM ( fact_sales[net_sales] ) - SUM ( fact_sales[cost_of_sales] )
+     formatString: #,0
+     displayFolder: 利益指標

このように 「どのビジュアルを」「どう変えたか」が PR の Files Changed タブで読み取れる。.pbix のバイナリ diff（「3 KB 増えました」しか分からない）と比べると、レビューの解像度が桁違いです。

5.3 PR レビューフロー

Azure DevOps の Pull Request 機能で、Power BI レポート / Notebook / SM のレビューが回ります。

レビュアーが PR で確認するポイント:

ファイル種別	レビュー観点
`visual.json`	ビジュアルの位置 / サイズ / データバインドが意図通りか
`.SemanticModel/` 配下 TMDL	メジャー / リレーションシップ / formatString の変更が想定通りか
`notebook-content.py`	Notebook ロジックの変更点・副作用の有無

PR description に「再現手順」「期待結果」を書いておくと、レビュアーが workspace 反映後に動作確認しやすくなります。

5.4 Issue / PR / commit が自動で相互リンクされる

Azure DevOps の自動リンク機能で、以下の相互リンク関係が組まれます。

Issue ページから「関連 PR」「関連 commit」のリンクが見える
commit ページから紐付け Issue / PR が辿れる
PR description / 各 commit メッセージから Issue が引ける

半年後に「なぜこの DAX 式に変更したか」を辿るとき:

git blame で該当行の commit を特定
commit メッセージから AB#42
Boards Issue を開いて意思決定の背景を確認

という流れで 意図まで到達 できます。.pbix 時代の「誰がいつ何を変えたか分からない」状態とは雲泥の差です。

6. 落とし穴と運用ルール

6.1 「Uncommitted」現象の正体（実害ゼロ）

Git sync を運用していると、updateFromGit で取り込んだ直後のアイテムが 「変更」タブに Uncommitted で出現 する現象に出くわします。

長らく原因が不明でしたが、検証の結果 Service が JSON を内部で 4-space indent に自動整形することによる whitespace の差分 と判明しました。

観察項目	結果
Power BI Desktop 編集 → push → updateFromGit	ポータルでアイテムが「Modified」表示
`fab export` で Service 内部を取得 → clone と diff	多数ファイルで差分検出
差分ファイルを JSON parse して `==` 比較	全件 logically equal（whitespace のみ）
原因	Desktop は 2-space / Service は 4-space で canonical 保存

つまり 動作には何の影響もない whitespace のずれ が、ポータル UI 上で「変更あり」として見えているだけです。

実用上の対処:

そのままポータル「コミット」（または commitToGit）で受け入れて OK
ただし放置すると後続の updateFromGit で Conflict 化リスクあり → その日のうちに commit-back する のが運用安全

6.2 Conflict が出たときの対処

「すべて更新」で Conflict が出ると、パネル下部に「競合の解決」ボタンが現れます。

クリックするとダイアログが開き、アイテムごとに 2 列のラジオで選択:

選択肢	動作	採用すべき場面
受信した変更を受け入れる	Git 側のバージョンで workspace を上書き	Git 側が信頼できる主ソース / workspace の Uncommitted は不要な差分
現在のコンテンツを保持する	workspace 側のバージョンを保持	workspace で意図的に変更した / Git 側を破棄したい

ダイアログには「一部の項目は完全に削除される場合があり、復元できません」という警告が出ますが、これは「workspace 側のバージョンを破棄する」ことに対する一般警告です。Git 側に元バージョンがあるケースでは実質ロスなし。

Git ベース開発を採用しているチームでは、ほぼ常に「受信した変更を受け入れる」一択 になります。workspace は read-mostly に近い扱い、Git が真実のソースという原則を貫けば判断がブレません。

6.3 Semantic Model + Report 統合改修の標準フロー（8 ステップ）

データ基盤の現実的な改修は「SM にメジャー追加 + Report の新ページで使う」のように SM と Report が同時に変わる ケースが多くあります。この場合の標準フロー:

Step 7 が重要です。Step 6 で「すべて更新」を実行した直後に、Service の 4-space 自動整形により 再び Uncommitted が発生 することがあります。これをその場で commit-back（または commitToGit）して同期を完全にクリーンにする。これにより次回の updateFromGit で Conflict が出るリスクを潰せます。

6.4 デプロイ経路の使い分けマップ

本記事の Git sync ルートと、第 5 回で扱う fab CLI ルート、ポータル UI 手動コミットの 3 つを比較すると次のとおりです。

ルート	構成	適する場面
Git sync ルート（本記事）	`git push` + ポータル「すべて更新」 or `updateFromGit` API	PR レビュー文化を入れたい / Desktop 編集を絡めたい / 履歴管理重視
`fab` CLI 直接ルート（第 5 回）	`fab import` + `fab api commitToGit`	Claude Code 完結 / 完全自動化 / スピード重視
ポータル UI 手動コミット	ポータル「コミット」「すべて更新」をクリック	1 件だけ / GUI で diff 確認したい

「すべてのケースで Git sync ルート」と決めるのではなく、作業の性質によって 3 ルートを使い分ける のが現実的です。本記事の Git sync ルートが活きるのは、PR レビューを挟みたい時・Desktop で .pbip を編集した時・履歴の透明性を重視する時 です。

7. まとめ + 第 5 回予告

7.1 振り返り

本記事で扱った要点を整理します。

.pbip + Fabric Git 統合 により、Power BI レポートとデータ基盤は「普通のソフトウェア開発」と同じ Git ベースのワークフローに乗ります
Issue 駆動の開発フロー で 1 周のループ（Issue → ブランチ → 編集 → PR → マージ → updateFromGit → Done）を回せます
開発者の主要なインタフェースは Claude Code で、複数ツール（git / Fabric MCP / Power BI Modeling MCP / fab CLI / Azure CLI / Boards）への呼び出しは Claude Code が裏で組み合わせます
Workspace ↔ Git ↔ ローカルクローンの 3 拠点同期 が成立し、ローカルクローンは保険 + PR ベース編集の起点として機能します
updateFromGit（ポータル「すべて更新」） で Notebook も .pbip Report も問題なくデプロイできます
「Uncommitted/Modified」現象 は Service の 4-space 自動整形が原因で実害ゼロ。Conflict が出ても「受信した変更を受け入れる」一択
SM + Report 統合改修の 8 ステップ標準フロー が安定パターンとして確立しています

7.2 第 5 回予告

次回（第 5 回）は 「Fabric の Git 連携をボタン操作なしで完全自動化する — CLI からのデプロイフロー」 を予定しています。

本記事では Step 6 で 「ポータル『すべて更新』をクリック」 が必要でしたが、第 5 回ではこのクリックを fab api 呼び出しで代替し、CLI 1 行に置き換える完全自動化フロー を扱います。

fab api commitToGit（workspace → Git の自動化）
fab api updateFromGit（Git → workspace の API 経由実行）
LRO（status 202）の正しい扱い方
「Uncommitted」現象を自動で commit-back するループ

連載のアークは 「土台 → カバー拡大 → 自動化」。第 4 回までで「人が開発する基盤」が整い、第 5 回で「ボタン操作なしの自動化」に踏み込みます。

7.3 関連リンク

公式ドキュメント:

Microsoft Learn: Overview of Fabric Git integration
Microsoft Learn: Git - Update From Git (REST API)
Azure DevOps: Drive Git development from work items（AB#ID 記法の自動リンク）

連載過去回:

Power BI は決して「Git 管理できないツール」ではなく、.pbip + Fabric Git 統合の登場で ソフトウェア開発と同じ Git ワークフローで運用できる ようになりました。Issue 駆動のフローに乗せると、データ基盤・BI 開発でも当たり前のように PR レビューと履歴管理が回り始めます。

質問・コメント・気付き、歓迎します。