書いたものを安全に本番へ届ける — Git 連携とデプロイの自動化

12.1Databricks Git Folders — sparse checkout、権限4種、Pull で出力が消えること、できないこと

ワークスペースの画面でノートブックを直接書き換えていると、昨日まで動いた処理が今日壊れたときに、誰がいつ何を変えたのかを追えません。手でエクスポートして手元の Git に置く運用も、差分が見えず競合も検出できません。Databricks Git Folders は、この「変更履歴がワークスペースの外にしか作れない」という困りごとを、ワークスペース内のフォルダをリモートの Git リポジトリに直結させて解決します。旧称は Databricks Repos で、2024 年に改称されました。変わったのは UI と用語だけで、REST API は改称されておらず `/api/2.0/repos` が現行の正式パスです。`/Repos` というワークスペースパスもそのまま機能します。

Git Folders の前段 — ノートブックとローカル IDE

つなぐ前に、ノートブック側の道具立てです。Python / SQL / Scala / R をセル単位で切り替えられ、`%sql` のような言語マジックはセルの 1 行目に置く必要があり、前に空行やコメントがあるとパースエラーになります。共通処理は `%run ./utils` で取り込み、呼び出し元と同じ実行コンテキストに展開されるので関数も変数もそのまま使えます。対して `dbutils.notebook.run("utils", 60)` は子を別コンテキストで起動し、受け取れるのは `dbutils.notebook.exit()` が返した文字列だけです。Revision history は Git とは別に自動保存され、消したセルを時刻を選んで戻せます。複数人の同時編集も可能で、排他ロックはかかりません。File > Export は `.dbc`、ソース形式 (セル境界は `# COMMAND ----------`)、`.ipynb`、HTML、R Markdown に対応し、上限は IPYNB が 100 MB、他は 10 MB です。ローカルの VS Code から書くときは Databricks Connect と VS Code 拡張を使います。

接続の準備 — 認証情報は個人設定に登録する

連携できるのは GitHub (Cloud / Enterprise Server)、GitLab、Bitbucket Cloud、Azure DevOps Services、AWS CodeCommit です。最初にやるのは、Settings の Linked accounts で個人アクセストークン (PAT) か OAuth を登録することです。ここを飛ばすと clone の時点で認証エラーになります。1 ユーザーが持てる Git 資格情報は最大 10 件で、プロバイダごとに 1 件が既定になります。Azure DevOps は Microsoft Entra ID のトークンに非対応で、Azure DevOps の PAT が必須です。

できること、できないこと

UI からは clone、ブランチの作成と切り替え、Commit & Push、Pull、差分表示、コンフリクト解消ができ、merge / rebase / reset (`git reset --hard` 相当) も実行できます。Create Branch で名前とベースブランチを選ぶと、作成と同時にチェックアウトされます。ただし試験で問われるのはできないことの側です。プルリクエストの作成は Git プロバイダ側の画面で行います。自動コミットも自動 push もなく、Commit & Push を押すまで何も届きません。`%git` というマジックも `databricks branches create` も存在しません。

Pull はノートブックの出力を消す

上流の変更を取り込む Git 操作は、ノートブックの状態をクリアします。Pull の後は、セルに表示されていた実行結果が失われます。残したい表やグラフは先にテーブルへ書き出してください。「Pull しても出力は保持される」は誤りという形で問われます。未コミットの変更が勝手にコミットされることもありません。

未コミットの変更があると、Pull はそもそも拒否されます。UI に stash ボタンはないため、変更を残すか破棄するかを選ぶダイアログ (Keep my changes / Discard my changes) で処理します。細かく残したいときは Git CLI 側で `git stash` → `git pull` → `git stash pop` を踏みます。行単位の競合は、その行を直接編集するか Take all incoming changes で片側を採用します。

覚えておく上限値

この上限のせいで 5 GB のリポジトリは clone に失敗します。10 MB は Git フォルダ内のファイルを UI で開けるかの制限で、ワークスペースファイル全般の話ではありません。

sparse checkout — 巨大なモノレポの一部だけを取り込む

モノレポをまるごと取り込むと、上の上限にすぐ当たります。sparse checkout は必要なディレクトリだけを取り込む機能です。Git folder 作成のダイアログで Sparse checkout mode を有効にし、Cone patterns の欄にパターンを改行区切りで並べます。パターンを書かずに有効化すると、ルート直下のファイルだけが対象になります。`parent/child/grandchild` と書くと grandchild 配下が再帰的に入り、途中の親ディレクトリとルート直下のファイルも入ります。`!` による除外指定は cone パターンにありません。作成後は Settings > Advanced > Cone patterns で編集できますが、後から無効化はできません。commit と push は通常どおり動きます。

権限は 5 段階、付与するのは 4 種

公式が列挙するのは NO PERMISSIONS を含む 5 段階で、付与するのは CAN READ 以上の 4 種です。権限は配下のすべてに適用され、個別の上書きもできます。この ACL (権限設定の一覧) は Premium プラン以上です。通常のフォルダの最下位は CAN VIEW、Git フォルダは CAN READ です。

本番ジョブが参照する Git フォルダは、管理者がユーザーフォルダの外に作り、デプロイ用ブランチだけを保持します。自動化を動かすサービスプリンシパル (人ではなく処理に割り当てる ID) には CAN RUN を与えます。個人フォルダ配下に置く構成や、全員への CAN MANAGE は事故の起点です。

12.2Asset Bundles の文法 — databricks.yml / targets / variables 解決順序5段 / mode: production / lookup

前節の Git Folders はコードの履歴を残してくれますが、ジョブやパイプラインの設定までは面倒を見てくれません。開発ワークスペースで画面から組み立てたジョブを、本番ワークスペースでもう一度作り直す。ここが実務でいちばん壊れます。タイムゾーンを直し忘れる、リトライ回数だけ違う、参照するカタログが dev のまま残る。こうしたずれは事故が起きるまで誰も気づきません。Declarative Automation Bundles は、ジョブ・パイプライン・クラスタ・ダッシュボードといった資産を YAML に一度だけ書き、環境ごとの差分だけを上書きしてデプロイすることで、このずれを構造的に防ぎます。呼び名は Databricks Asset Bundles から Declarative Automation Bundles へ変わりましたが、CLI は `databricks bundle` のままで、設定ファイルの書き換えも要りません。試験では両方出ます。

databricks.yml のトップレベルは 14 個

バンドルの中核は、プロジェクトのルートに置く `databricks.yml` です。書けるトップレベルのマッピングは次の 14 個で、必須は `bundle` と、その配下の `name` だけです。`bundle` は 1 ファイルに 1 つしか書けません。

この一覧は CLI のバージョンで増減します。`scripts` は CLI 0.259.0 で追加され、`python` は 0.275.0 で `experimental` から昇格しました。CLI が古いと書いたキーは無視されます。

bundle:
  name: etl_pipeline

include:
  - resources/*.yml

variables:
  catalog_name:
    default: main

resources:
  jobs:
    daily_ingest:
      name: "${bundle.target}_daily_ingest"
      tasks:
        - task_key: transform
          notebook_task:
            notebook_path: ./src/transform.py

targets:
  dev:
    default: true
    mode: development
    workspace:
      host: https://dev.cloud.databricks.com
  prod:
    mode: production
    workspace:
      host: https://prod.cloud.databricks.com
    variables:
      catalog_name: prod_main

`include` に `resources/*.yml` のようなグロブを書くと、ジョブごとにファイルを分けても 1 つのバンドルとして扱われます。分けてよいのはファイルであってバンドルではありません。環境ごとにバンドルを分けた時点で、二重管理に戻ります。リソース名に `${bundle.target}` を埋め込んでいるのは、同じワークスペースに dev と prod を並べたときの名前衝突を避けるためです。

デプロイ先のパスには既定値がある

`workspace.host` を書かなければ CLI のプロファイルの接続先が使われます。パス類は書かなければ次の既定値になります。

既定のままだと、デプロイした人のユーザーフォルダ配下に成果物が置かれます。本番では `root_path` を個人に依存しない場所へ移し、書き込めるのはサービスプリンシパルだけにします。

targets — 環境差分はここだけに書く

`targets` の配下に `dev` `staging` `prod` を宣言し、それぞれで `workspace.host`、`mode`、`variables`、リソースの一部を上書きします。デプロイは `databricks bundle deploy -t prod` のように `-t` (`--target`) で 1 つの target を選んで行います。1 コマンドでデプロイされるのは 1 target だけで、同時並列に全環境へ配ることはありません。`default: true` を付けられる target はちょうど 1 つで、これを付けておくと `-t` を省略できます。CI では環境変数 `DATABRICKS_BUNDLE_ENV` でも target を指定できます。

`bundle.name` はワークスペース上でのリソースの名前空間として働き、ジョブ名やパイプライン名に織り込まれます。開発者や target が複数あっても衝突しないのは、この仕組みのおかげです。実行 ID を固定したいときは `run_as` に `user_name` か `service_principal_name` を書き、配布したリソースに付ける権限は `permissions` にグループ単位で書きます。

variables — `${var.…}` と complex と lookup

変数は `variables` で宣言し、参照は `${var.catalog_name}` の形です。`$ENV{...}` や `%name%` や `{{variables.name}}` はバンドルの構文ではありません。カスタム変数は既定で文字列として扱われるため、クラスタ構成のように入れ子の値をまとめて切り替えたいときは、変数定義に `type: complex` を指定します。`type: complex` なのに `default` が単一の値だと、検証で失敗します。

variables:
  job_cluster:
    type: complex
    default:
      node_type_id: i3.xlarge
      num_workers: 2
  shared_cluster_id:
    lookup:
      cluster: "team-shared-cluster"

既存オブジェクトの ID をハードコードしたくないときは `lookup:` を使います。名前を書くと ID が解決されます。対応するのは alert / cluster_policy / cluster / dashboard / instance_pool / job / metastore / notification_destination / pipeline / query / service_principal / warehouse の 12 種類です。

変数の解決順序は 5 段

同じ変数に複数の場所で値が指定されているとき、CLI は上から順に探し、最初に見つかった時点で確定します。

書き方は `--var="catalog_name=foo"`、環境変数なら `BUNDLE_VAR_catalog_name=foo` です。CI から一時的に値を差し込みたいときに `--var` が最優先になる、という順序です。「default が最優先」「targets が --var より強い」といった選択肢は誤りです。

mode: development と mode: production

`mode` は target ごとに書くフラグで、ガードレールの束をまとめて切り替えます。

`mode: production` のデプロイ時に CLI が行う検証は 3 つ覚えます。デプロイされる Lakeflow パイプライン (宣言的にテーブルを作るパイプライン機能) がすべて `development: false` であること、現在の Git ブランチが target に指定されたブランチと一致すること (`--force` で上書き可)、そしてサービスプリンシパルを使わない場合は `root_path` などのパスがユーザー固有になっていないことと `run_as` と `permissions` が明示されていることです。通知先メールの有無や、全タスクがサーバーレスかどうかは検証されません。

mode が入れる既定値は `presets` で個別に上書きできます。キーは `name_prefix`、`tags`、`pipelines_development`、`trigger_pause_status`、`jobs_max_concurrent_runs`、`source_linked_deployment`、`artifacts_dynamic_version` の 7 つです。

シークレットは YAML に書かない

接続文字列やトークンを `databricks.yml` に平文で書くと、Git の履歴に永久に残ります。バンドルからは Secret スコープを参照し、値そのものは持ち込みません。参照の構文は `{{secrets/<scope-name>/<secret-name>}}` で、`{{secrets/` で始まり `}}` で終わります。波かっこの内側に空白を入れるとスコープ名やキー名の一部として扱われるため、詰めて書きます。

12.3Databricks CLI と CI/CD パイプライン — bundle サブコマンド、GitHub Actions 連携、アンチパターン集

ここまでの YAML を実際に動かすのが Databricks CLI です。CLI は開発者の手元と CI ランナーの両方で同じコマンドを実行できるため、「自分の環境では動いた」という言い訳が生まれません。

まず認証を通す

手元では `databricks auth login --host <workspace-url>` を実行すると、設定プロファイルが `~/.databrickscfg` に保存されます。以後は `-p` (`--profile`) でプロファイルを選びます。CI では対話ログインができないため、環境変数を使います。CLI はバンドルの設定ファイル、`DATABRICKS_HOST` / `DATABRICKS_TOKEN` / `DATABRICKS_CLIENT_ID` / `DATABRICKS_CLIENT_SECRET` などの環境変数、`.databrickscfg` のプロファイルの順に資格情報を探し、見つかった時点で止まります。CI で使う ID は個人ではなくサービスプリンシパルにし、デプロイ用と実行用 (`run_as`) を分けます。

bundle サブコマンド

UI で手作りしてしまった既存ジョブをコード化したいときは `databricks bundle generate job` を使います。`generate` には app / dashboard / genie-space / job / pipeline のサブコマンドがあり、`--bind` を付けると生成した定義を既存リソースに紐づけられます。紐づけは後から `databricks bundle deployment bind` と `unbind` でも操作できます。実行は `databricks bundle run daily_etl -t prod` のようにリソースキーを引数に取ります。

選択肢に混ぜられる存在しないコマンドも覚えておくと得点になります。`bundle test`、`bundle check --dry-run`、`bundle undeploy`、`bundle clean`、`bundle import job`、`databricks jobs export --to-bundle`、`databricks branches create` はいずれも存在しません。`--validate-only` は `deploy` ではなく `run` のフラグである点も引っかけになります。

GitHub Actions に載せる

標準の型は、CLI を入れて、認証を通して、`validate` してから `deploy` する、の 4 ステップです。認証はワークロード ID フェデレーション (OIDC。人ではなくワークフローの実行そのものに、短命の身分証を発行してもらう仕組み) が推奨で、この場合はワークスペースのトークンを GitHub 側に保存する必要がなくなります。

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      DATABRICKS_AUTH_TYPE: github-oidc
      DATABRICKS_HOST: ${{ vars.DATABRICKS_HOST }}
      DATABRICKS_CLIENT_ID: ${{ vars.DATABRICKS_CLIENT_ID }}
      DATABRICKS_BUNDLE_ENV: prod
    steps:
      - uses: actions/checkout@v4
      - uses: databricks/setup-cli@main
      - run: databricks bundle validate
      - run: databricks bundle deploy

CLI の導入は公式アクション `databricks/setup-cli` で行い、`@main` かバージョンを固定した参照を書きます。ブランチと target の対応づけが設計の勘所です。PR では dev target へ `validate` と `deploy` を流し、main へのマージで prod target へデプロイします。`id-token: write` がないと OIDC のトークンを発行できず認証に失敗するので、権限ブロックの書き忘れは典型的な詰まりどころです。

アンチパターン集

`targets` の設定が足りないときの怖さは、デプロイが失敗せずに通ってしまうことです。構文が正しければ deploy 自体は成功し、dev 用のジョブが本番のジョブを上書きしてから気づきます。逆に特定の環境だけ deploy が失敗するなら、その target ブロックで参照しているカタログ名・外部ロケーション名・ワークスペースパスの誤りをまず疑います。

開発から本番までの流れ

ここまでの部品をつなぐと 1 本の線になります。

1. Git Folders で作業ブランチを切り、ノートブックを書く。共通処理は `%run ./utils` か Python モジュールの import で共有する。
2. Commit & Push し、Git プロバイダの画面でプルリクエストを作る。
3. PR をトリガーに CI が `databricks bundle validate` と dev target への `deploy` を実行し、`bundle run` でテスト用ジョブを回す。
4. レビューを通してマージすると、main のワークフローが prod target へ `deploy` する。`mode: production` の検証がここで効く。
5. 本番ジョブは、バンドルが配置した成果物か、管理者が用意した本番用 Git フォルダのデプロイ用ブランチを参照して動く。

手作業に戻した瞬間に再現性と監査性が失われます。覚えることは「開発は Git Folders、配布は Bundles、実行は CI から CLI」の 3 点です。

この章は開発から本番までの流れを一本の線として示すところまでです。GitHub Actions と Azure DevOps のワークフロー例、環境差分の具体的な配布設計、Git フォルダの日々の運用は、それぞれ専用の解説記事で扱います。