Codatum CLI

Appearance

GitHubで管理 ​

概要 ​

ノートブックを複数人で扱うようになると、誰がいつ何を変えたのか、変更前にレビューできるか、といった運用上の課題が出てきます。ノートブックファイル（.cnb.md）を GitHub で管理すれば、通常のコードと同じように、変更を Pull Request でレビューし、承認されたものだけを反映する、という流れに乗せられます。

このユースケースでは、GitHub をマスタとし、変更が main にマージされたタイミングで GitHub Actions が Codatum に反映する構成を説明します。GitHub で管理するのはノートブックの構造（SQL・チャート・パラメータ・レイアウト）です。データの最新化（ノートブックの実行）は Codatum 側で都度行うものとし、ジョブの実行状態は Git の管理対象に含めません。これにより、実行のたびに差分が発生してノイズになることを防ぎます。

  • 主役: GitHub をマスタにした反映フローと、それを支える GitHub Actions
  • 題材: 対話でダッシュボードを作成 で作ったダッシュボード
  • 成果物: PR で検証し、マージで Codatum に反映する 2 つの GitHub Actions ワークフロー

完成形の設定例は codatum-cli-examples リポジトリ（use-cases/03-manage-with-github/）で公開しています。

このユースケースは CI を主役にしています。ここでは GitHub Actions を例にしていますが、cdm は CDM_PAT 環境変数で認証でき、各コマンドは異常終了時に終了コードを返すため、他の CI でも同様の構成を取れます。

全体の流れ ​

GitHub をマスタにした運用は、次の 3 つのステップに分かれます。

  1. ローカルで編集する: 各メンバーは閲覧用の PAT で cdm notebook pull し、.cnb.md を編集して cdm notebook preview で確認します。手元から Codatum への反映はしません。
  2. Pull Request で検証する: 変更を Github に push して PR を開くと、GitHub Actions が .cnb.md を検証します。あわせて Github 上で差分をレビューします。
  3. マージで反映する: PR が main にマージされると、GitHub Actions が編集用の PAT で cdm notebook push を実行し、Codatum に反映します。

変更の反映の方向は GitHub → Codatum の一方向です。Codatum 側で直接ノートブックが編集された場合、一時的に Github と Codatum の間で差異が生じますが、次の PR がマージされたタイミングで Github 側を正本として上書きされます。

準備 ​

このユースケースは 対話でダッシュボードを作成 で作ったダッシュボードを題材にします。先にそちらを済ませ、手元に .cnb.md がある状態から始めるとスムーズです。

1. ノートブックをロックする ​

GitHub で管理するノートブックは、Codatum 上で「クエリのみ」モードにロックします。ノートブックのメニューから「クエリのみ（パラメータの変更とクエリ実行のみ可能）」を選ぶと、SQL やチャートといった構造の編集が UI から禁止され、構造の変更は GitHub 経由だけに限定されます。これにより GitHub が常にマスタである状態を保ちつつ、利用者は UI 上でパラメータを変えたりクエリを実行したりして、ダッシュボードをそのまま使えます。

2. PAT を用意する ​

役割の異なる 2 つの PAT を発行します。権限を分けることで、手元から誤って反映してしまう事故を防ぎ、CI が触れる範囲を最小化できます（PAT の権限の仕組みは PATと権限 を参照）。

  • 閲覧用 PAT（各メンバーの手元）: 各メンバーが cdm auth login のブラウザでの承認から発行し、自分の手元に登録します。承認画面で「トークンの権限を制限する」を有効にし、対象フォルダの閲覧権限のみに絞ります。閲覧権限のみでは cdm notebook push できないため、手元から誤って更新するリスクを減らせます
  • 編集用 PAT（GitHub Actions の Secret）: CI ではブラウザでの承認を使えないため、Codatum のWebサービスの 「アカウント設定」 → 「パーソナルアクセストークン」 から手動で発行します。対象フォルダに絞った閲覧・編集権限を与え、cdm notebook push に使います

GitHub の Secret に登録するのは編集用 PAT だけです（例: CDM_PAT）。閲覧用 PAT は各メンバーの手元にとどめ、Secret には登録しません。

3. ノートブックをリポジトリに置く ​

「クエリのみ」に設定したノートブックを cdm notebook clone で取得し、リポジトリにコミットします。以降、このファイルが GitHub 上のマスタになります。

使い方 ​

ローカルで編集する ​

各メンバーは、閲覧用 PAT で最新を取得してから編集します。

sh
cdm notebook pull notebooks/
# .cnb.md を編集
cdm notebook preview notebooks/theLook-Sales-Dashboard.cnb.md

cdm notebook preview はブラウザと双方向に同期しながら編集できます。編集が済んだら、コミットする前に cdm notebook format で整形・自動修復し、cdm notebook strip で実行結果とジョブ実行状態を取り除きます。.cnb.md は通常のマークダウンとフォーマットが異なるため、手動で整形せず、必ず format を通します。strip は、ジョブの実行状態を Git に持ち込まないために行います。

sh
cdm notebook format notebooks/
cdm notebook strip notebooks/

整形・コミットが済んだら、ブランチを切って push し、PR を開きます。手元からサーバへは反映しません。

Pull Request で検証する ​

PR を開いたときに、GitHub Actions で .cnb.md を検証します。スキーマ・構文の検証には cdm notebook validate を使います。スキーマや構文にエラーがあれば exit 1 で終了するため、問題があれば PR のチェックが失敗します。

あわせて、cdm notebook strip --check でジョブ実行情報が取り除かれていることを確認します。ジョブ実行情報が残っている場合は exit 1 で終了するため、問題があれば PR のチェックが失敗します。

format や strip はファイルを書き換える操作なので、コミット前にローカルで済ませておく前提とし、CI では書き換えを伴わない validate と strip --check だけを行います。

CDM_PAT 環境変数が設定されていると、cdm はその PAT を使って認証します（詳細は 環境変数によるオーバーライド）。このワークフローでは Github Actions の Secret に登録した編集用 PAT を使います（検証用と反映用で同じ Secret を使います）。

.github/workflows/validate.yml:

yaml
name: Validate notebooks

on:
  pull_request:
    paths:
      - "notebooks/**/*.cnb.md"

jobs:
  validate:
    runs-on: ubuntu-latest
    env:
      CDM_PAT: ${{ secrets.CDM_PAT }}
    steps:
      - uses: actions/checkout@v4

      - name: Install cdm
        shell: bash
        run: |
          set -euo pipefail
          curl -fsSL https://cli-dist.codatum.com/install.sh | sh

      - name: Validate schema and syntax
        run: cdm notebook validate notebooks/

      - name: Check notebooks are stripped
        run: cdm notebook strip notebooks/ --check

差分のレビューは、GitHub 上の .cnb.md の差分で行えます。サーバに反映した場合の差分を確認したい場合は、ローカルで cdm notebook diff を使います。

マージで反映する ​

PR が main にマージされると、GitHub Actions が編集用 PAT で cdm notebook push を実行し、Codatum に反映します。push は送信前にノートブックを検証し、エラーがあれば反映せずに終了します。CI では確認プロンプトを避けるため --yes を指定します。あわせて --ignore-job-metadata を指定し、ジョブの実行状態には触れずに構造だけを反映します。これにより、Codatum 側で都度実行されている最新のジョブ状態を上書きしません。

.github/workflows/deploy.yml:

yaml
name: Deploy notebooks

on:
  push:
    branches:
      - main
    paths:
      - "notebooks/**/*.cnb.md"

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      CDM_PAT: ${{ secrets.CDM_PAT }}
    steps:
      - uses: actions/checkout@v4

      - name: Install cdm
        shell: bash
        run: |
          set -euo pipefail
          curl -fsSL https://cli-dist.codatum.com/install.sh | sh

      - name: Push to Codatum
        run: cdm notebook push notebooks/ --yes --ignore-job-metadata

次のステップ ​

設定例一式は codatum-cli-examples リポジトリ を参照してください。

Codatum CLI AIエージェントのための分析環境

© Codatum Inc.