Claude Code × Microsoft Fabric (4) － Power BI レポートとデータ基盤を Git で管理する：Issue 駆動の開発フロー実践

Posted at 2026-05-23

想定読者

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 レビューと履歴管理が回り始めます。

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

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up