本記事は ZOZO Advent Calendar 2023 シリーズ 7 の 5 日目の記事です。

概要

dbt はコマンド1つでリネージュを含むリッチなドキュメントサイト(dbt Docs)を自動生成してくれるのがとても便利です。
ところが dbt-core (OSS版)を利用している場合は自前で dbt Docs をホスティングする必要があります。
今回は Github Pages 上でのホスティングを利用しつつ、Github Actions を使って main ブランチにマージした内容でdbt docsコマンドを実行しサイト反映する方法を紹介します。

前提として BigQuery を利用する場合を想定し、 OIDC を利用した Google Cloud 認証を記載していますが、データベースによって適宜置き換えてください。
また本記事では認証方法については深く触れません。

Github Pages の設定

Github の該当リポジトリの設定画面で Pages に遷移します。
Build and deployment セクションのBranch設定でmain、フォルダとして/docsを選択します。

Github で加入しているプランによって、ページを非公開にすることができないのでご注意ください。

docs ディレクトリの追加

dbt Docs のホスティングに必要なファイル(dbt artifacts)を保管しておくためのディレクトリを用意します。
該当リポジトリのルートディレクトリでdocsディレクトリを追加、Push しておきます。

mkdir docs

Github Actions の実装

Github Actions は以下のように実装します。
dbt Docs のホスティングに必要なファイル(dbt artifacts)は以下の3つなので、それらを一時的に生成される target ディレクトリ配下から、先ほど作成した docs ディレクトリ配下にコピーして保持しています。

index.html
catalog.json
manifest.json

name: Release dbt project
on:
  pull_request:
    branches:
      - main
    types: [closed]

env:
  WORKLOAD_IDENTITY_PROVIDER: # Google Cloudの認証に利用するWorkload Identity Providerを指定
  SERVICE_ACCOUNT: # Google Cloudの認証に利用するサービスアカウントを指定

jobs:

  generate-dbt-docs:
    if: ${{ !failure() && github.event.pull_request.merged == true}}
    runs-on: ubuntu-22.04
    permissions:
      contents: write
      id-token: write

    steps:
    - name: Check out repository code
      uses: actions/checkout@v4
      with:
        fetch-depth: 0

    - name: Authenticate to GCP
      id: auth
      uses: google-github-actions/auth@v1
      with:
        workload_identity_provider: ${{ env.WORKLOAD_IDENTITY_PROVIDER }}
        service_account: ${{ env.SERVICE_ACCOUNT }}
    
    - name: Set up Cloud SDK
      uses: google-github-actions/setup-gcloud@v1

    - name: Login to GCP
      run: |
        gcloud auth login --brief --cred-file="${{ steps.auth.outputs.credentials_file_path }}"

    - name: Set up Python 3.11.4
      uses: actions/setup-python@v4
      with:
        python-version: 3.11.4
    
    - name: Install dbt
      run: |
        pip install dbt-core dbt-bigquery
        dbt deps

    - name: Generate dbt docs
      run: |
        dbt docs generate
    
    - name: Copy to docs directory
      run: |
        cp target/index.html target/catalog.json target/manifest.json docs/

    - name: Auto Commit & Push changes
      uses: stefanzweifel/git-auto-commit-action@v5
      with:
        branch: main
        commit_message: Generate dbt docs
        file_pattern: 'docs/*.html docs/*.json'

あとは main ブランチに対してマージする度に、Github Pages 上のホスティングサイトに反映されるようになります。
実際に意図したページが表示されているかどうか、ホスティング URL にアクセスしてご確認ください。

もし環境ごとに target を切り分けていて、ドキュメントのリネージュに表示される依存関係を本番向けにしたい場合は、dbt docs generate --target prdというように--targetオプション付きで実行する必要があります。
そのほかにもコマンド実行時に必要なオプションがあれば適宜付与しましょう。

まとめ

本記事では dbt のドキュメントを共通管理するために、Github Actions を使って Github Pages 上でdbt Docs をホスティングする方法を紹介しました。
dbt Docs をホスティングする方法はいくつかありますが、既に dbt を Github でコード管理している場合は気軽だと思います。
これからも dbt 界隈が盛り上がることを期待しています！

Github Actionsでdbt Docsを生成しGithub Pages上でホスティングする

概要

Github Pages の設定

docs ディレクトリの追加

Github Actions の実装

まとめ