本記事は 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 界隈が盛り上がることを期待しています!