CI でスキーマを反映する

コンテンツタイプとフィールドの形（スキーマ）を、スキーマのファイル（.hako.json）として、サイトのコードと同じリポジトリに置けます。ファイルを変えたら、差分を確かめてから、CI でスペースに反映します。スキーマのファイルは、試しのスペースで作ったコンテンツタイプを本番のスペースに揃えるのにも使えます。

前提

hakocms-cli を入れ、ログインしておきます（CLI を入れる、CLI でログインする）
反映する先のスペースで、コンテンツタイプを変えられるロール（オーナー、管理者）を持っています

スキーマのファイルを取り出す

今のスペースのスキーマを、ファイルに取り出します。

hakocms-cli schema pull --space blog

✓ Saved blog.hako.json (612 bytes)

blog.hako.json にはスペースのすべてのコンテンツタイプと、そのフィールドが入っています。エントリーとメディアは入りません。

{
  "format": "hako-space",
  "version": 1,
  "source": { "space": "blog", "spaceName": "ブログ" },
  "contentTypes": [
    {
      "endpoint": "posts",
      "name": "記事",
      "kind": "collection",
      "schema": {
        "fields": [
          { "fieldId": "title", "name": "タイトル", "required": true,
            "kind": "text", "unique": false },
          { "fieldId": "body", "name": "本文", "required": false,
            "kind": "textArea" }
        ]
      }
    }
  ]
}

フィールドの書き方はフィールドの種類と値の形にあります。このファイルをリポジトリに入れます。

差分を確かめる

ファイルを直したら、スペースに反映する前に、何が変わるかを確かめます。schema diff は何も変えません。

hakocms-cli schema diff blog.hako.json --space blog

コンテンツタイプごとに、足すものには +、変えるものには ~、消すものには - が付いて表示されます。変えるフィールドと、新しいスキーマに合わなくなるエントリーの数も表示されます。

apply o4itgj7ry38v: queued
apply o4itgj7ry38v: planned
+ news (create)
~ posts (update: ~fields.title, ~fields.body, 2 entries violate)

ファイルにないコンテンツタイプは、次のように表示されます。--prune を付けて反映しないかぎり、消えません（下の「消すときと、合わないエントリーがあるとき」）。

- posts (delete with 2 entries; needs --prune)
  unchanged: news

変えるものがなければ、No changes と表示されます。

手元で反映する

hakocms-cli schema apply blog.hako.json --space blog

差分が表示され、反映してよいかを聞かれます。y を押すと反映されます。

✓ Applied the schema to blog

変えるものがなければ、何もせずに No changes と表示され、終了コード 0 で終わります
反映できない理由（今のエントリーの値が新しいスキーマに合わない、など）があれば、何も変えずに理由を表示し、終了コード 1 で終わります

消すときと、合わないエントリーがあるとき

ふだんの schema apply は安全な変更だけを行います。次の変更にはフラグが要ります。

変更	要るフラグ	何が起きるか
ファイルにないコンテンツタイプを消す	`--prune`	そのコンテンツタイプは、中のエントリーごと消えます。元に戻せません
今のエントリーの値が、新しいスキーマに合わない（必須にした、最大の文字数を減らした、など）	`--allow-violations`	合わないエントリーは、そのまま残ります。次に公開するときに、直すよう求められます

フラグが足りないときは、何も変えずに、理由を表示して終了コード 1 で終わります。

error: the schema cannot be applied:
posts: 2 entries violate the new schema; confirm to apply anyway (HTTP 409)

--prune を付けないと、ファイルにないコンテンツタイプは、スペースに残ったままになります。ほかに変えるものがなく、消すことだけが差分のときは、error: there is nothing to apply と表示され、終了コード 1 で終わります。

GitHub Actions で反映する

リポジトリの schema/blog.hako.json を変えて main に入れたら、本番のスペースに反映する例です。

管理画面で、CI 用のアクセストークンを作ります。［名前］は「GitHub Actions」、［できること］は［すべて（あなたと同じ）］にします（管理画面で作ったトークンでログインする）。
GitHub のリポジトリの［Settings］>［Secrets and variables］>［Actions］で、HAKOCMS_TOKEN という名前で、トークンを secrets に入れます。
次のワークフローを、.github/workflows/hakocms-schema.yml に置きます。<ホスト名> は、あなたの環境のホスト名に置き換えます。

name: Hako CMS schema

on:
  pull_request:
    paths: ["schema/**"]
  push:
    branches: [main]
    paths: ["schema/**"]

permissions:
  contents: read

jobs:
  schema:
    runs-on: ubuntu-latest
    env:
      HAKOCMS_HOST: https://<ホスト名>.hakocms.net
      HAKOCMS_TOKEN: ${{ secrets.HAKOCMS_TOKEN }}
      HAKOCMS_SPACE: blog
      # 使う版を決めておく（latest.json の version。上げるときは、ここを変える）
      HAKOCMS_CLI_VERSION: "0.1.8"
    steps:
      - uses: actions/checkout@v7
      - name: Install hakocms-cli
        run: |
          base=https://download.hakocms.net/hakocms-cli/v$HAKOCMS_CLI_VERSION
          name=hakocms-cli-v$HAKOCMS_CLI_VERSION-x86_64-unknown-linux-musl
          curl -fsSLO "$base/$name.tar.gz"
          curl -fsSLO "$base/SHA256SUMS"
          grep " $name.tar.gz\$" SHA256SUMS | sha256sum -c -
          tar xzf "$name.tar.gz"
          sudo install "$name/hakocms-cli" /usr/local/bin/
      # PR では差分だけを見る（何も変えない）
      - if: github.event_name == 'pull_request'
        run: hakocms-cli schema diff schema/blog.hako.json
      # main に入ったら反映する
      - if: github.event_name == 'push'
        run: hakocms-cli schema apply schema/blog.hako.json --force

CI では反映してよいかを聞けないので、--force を付けます。付けないと、needs --force when it cannot ask と表示されて、何も変えずに終わります
PR の差分はワークフローの実行のログに出ます
消す変更や、合わないエントリーのある変更（--prune、--allow-violations）は、CI に任せず、手元で差分を見てから反映することを勧めます
使う版は決めておきます。latest.json で毎回いちばん新しい版を入れると、CLI が新しくなったときに、知らないうちに動きが変わることがあります。いちばん新しい版の番号は https://download.hakocms.net/hakocms-cli/latest.json の version で分かります

確かめる

管理画面で、反映したスペースのコンテンツタイプを開きます。ファイルと同じフィールドが並んでいます。

手元から確かめるときは、もう一度 schema diff を実行します。No changes と表示されれば、ファイルとスペースが揃っています。

エントリーの型を作る

（省略可）スキーマから、エントリーの TypeScript の型を作れます。サイトのコードで、Content API の応答に型を付けるのに使えます。

hakocms-cli schema types --space blog > src/hakocms-types.ts

GraphQL のスキーマ（--format graphql）と、Content API の OpenAPI（--format openapi）も作れます。