Zendesk GuideのテーマをGitHubで管理する

この記事は毎週必ず記事がでるテックブログ Loglass Tech Blog Sprint の 33 週目の記事です！
1 年間連続達成まで 残り 20 週 となりました！

株式会社ログラス CRE（Customer Reliability Engineer）の @zaki___yama です。

弊社ではユーザー向けヘルプサイトの構築に Zendesk (https://www.zendesk.co.jp/)の Guide 機能を使用しています。Guide にはテーマのカスタマイズ機能があり、たとえば全体的な色味を自社のブランドカラーと合わせたり、テンプレートをカスタマイズすることでデザインだけでなく機能を拡張することが可能です。
弊社でもこれまで Guide のテーマには何度か軽微なカスタマイズを加えてきましたが、すべて管理画面から直接行っていました。
その結果、どういった経緯で・どういうカスタマイズを加えたのか、という歴史的経緯を紐解くのが難しい状態になっていました。

幸い Guide のテーマは GitHub との連携機能を提供しており、これを機に GitHub での管理を試してみました。
環境構築の手順や注意点を紹介します。

Guide の記事そのものを GitHub で管理する機能は Zendesk が提供していないため、本記事でも触れていません。

GitHub 連携をはじめる手順

GitHub リポジトリにテーマを準備する

まずは、管理対象となる GitHub リポジトリを作成し、テーマを準備します。
Guide のテーマ管理画面（https://***.zendesk.com/theming/workbench）にアクセスし、管理したいテーマのメニューから「ダウンロード」を実行します。

そして、ダウンロードしたファイルを GitHub のリポジトリにコミット・プッシュしておきます。

別の方法として、Zendesk の標準テーマ（Copenhagen）は GitHub のリポジトリでも公開されています。

https://github.com/zendesk/copenhagen_theme

このリポジトリを fork して始めるという方法もあります。
ただし、CI やビルド関連など、テンプレートそのものには必要ないファイルも含まれています。

Zendesk で GitHub 連携を設定する

準備したリポジトリを Zendesk と連携します。
Guide のテーマ管理画面から「テーマを追加」>「GitHub から追加」を選択します。

あとはダイアログに従い、準備したリポジトリのユーザー名・リポジトリ名、およびブランチ名（任意。省略するとデフォルトのブランチ）を入力します。

成功すると、テーマライブラリにテーマが追加されます。
これで、テーマを GitHub リポジトリ上でカスタマイズする準備が整いました。

ローカル環境でテーマ変更をプレビューする

Zendesk CLI（ZCLI） を使うと、ローカルでファイルを変更した結果を Zendesk Guide 上でプレビューできます。
ZCLI については以前別の記事でも紹介したので、こちらの記事のインストールおよび認証の項を参考にしてください。

https://zenn.dev/loglass/articles/zendesk-app-getting-started

認証まで済んだら、リポジトリのルートで zcli themes:preview というコマンドを実行します。

$ zcli themes:preview
Uploading theme... Ok
Ready https://zaki-yama.zendesk.com/hc/admin/local_preview/start 🚀
You can exit preview mode in the UI or by visiting https://zaki-yama.zendesk.com/hc/admin/local_preview/stop

コンソールに表示されている Ready の横のリンクをブラウザで開くと、Guide のページがプレビューモードで開きます。
プレビューモードで開いていることは、ページ上部のヘッダーで確認できます。

この状態でリポジトリ内のファイルを変更すると、ブラウザが自動的に更新され、変更内容をプレビューできます。

例：style.css を編集してボタンの色を変える

変更をリリースする

ローカルでの変更が完了したら、変更内容を Guide の設定にも反映します。
まず、テーマに含まれているマニフェストファイル（manifest.json）内のバージョン番号を更新します。

manifest.json

 {
   "name": "My Zendesk Theme",
   "author": "Zendesk",
-  "version": "3.2.0",
+  "version": "3.2.1",
   "api_version": 3,
   "default_locale": "en-us",
   "settings": [

テーマを更新する際、必ずバージョン番号を現行の数字よりも増やす必要があります。
現行バージョンからどれだけ増やすかは自由です。
また、バージョン番号の形式は Semantic Versioning に従うため、MAJOR.MINOR.PATCHの形式である必要があります（例： 3.2.0）。
バージョン番号を増やしたら、リポジトリにコミット・プッシュします。

最後に、テーマの管理画面より、GitHub 連携しているテーマのメニューから「GitHub から更新」を選びます。

表示されているリポジトリ・ブランチ名が正しいことを確認し、「更新」をクリックします。

以上で、テーマを GitHub で管理する一連の流れを紹介しました。

GitHub 管理にするメリット・デメリット

テーマを GitHub で管理するメリットとして、変更履歴や差分を容易に確認できる点や、Pull Request を使ったレビューフローを構築できる点などが挙げられます。
また、JS や CSS ファイルに関しては、ライブラリやビルドツールを使うことができる点もメリットとしてあるでしょう。
たとえば公式の Copenhagen テーマのリポジトリ を見ると、JS や CSS のコンパイルに rollup や Sass を使用しています。

反面、デメリットとしては、ちょっとした修正であっても GitHub 経由で行わなければならないため、git や GitHub に習熟していないメンバーはやや敷居が高いと感じるでしょう。このあたりは Guide を管理するメンバーのスキルセットやチームの規模感によってどちらが適しているか変わってきそうです。
また、手順の中でも触れましたが、変更をリリースするために毎回必ずマニフェストのバージョンを上げない点はちょっと使いにくさを感じました。

Tips

マニフェストファイル　（manifest.json）の中身

テーマに含まれるマニフェストファイル（manifest.json）について補足します。
manifest.json は次の表に示すプロパティを持ちます。

プロパティ名	タイプ	意味
name	文字列	テーマ名
author	文字列	テーマ作成者
version	文字列	バージョン
api_version	文字列	Templating APIのバージョン。基本は 3 のままでいいと思われる
settings	配列	設定オブジェクトのリスト

例として、公式の Copenhagen テーマ の manifest.json はこのようになっています。
（v3.2.2 で確認）

manifest.json

{
  "name": "Copenhagen",
  "author": "Zendesk",
  "version": "3.2.2",
  "api_version": 3,
  "default_locale": "en-us",
  "settings": [
    {
      "label": "colors_group_label",
      "variables": [
        {
          "identifier": "brand_color",
          "type": "color",
          "description": "brand_color_description",
          "label": "brand_color_label",
          "value": "#17494D"
        },

        ...

設定オブジェクト（settings）についてさらに掘り下げると、文字列のlabel と配列の variables で構成されます。
variables は 変数オブジェクト と呼ばれ、次のプロパティを持つオブジェクトです。

プロパティ名	意味
identifier	変数の識別子。英数字とアンダースコアのみが使える
type	変数の型。Guide の設定パネルの UI がこれによって決まる text, list, colorなどがある
label	設定パネルに表示されるラベル名
description	設定パネルに表示される説明
value	デフォルト値
options	list型のみで使用。値の選択肢
min	range型のみで使用。範囲の最小値
max	range型のみで使用。範囲最大値

この変数オブジェクトには 2 つの特徴があります。
1 つは、ここで定義した変数はテンプレート（.hbs）や CSS ファイル内で文字とおり変数として使える点です。
たとえば CSS ファイル内で

style.css

.blocks-item-internal a {
  color: $text_color;
}

のように書くことで、値を直接書かずに manifest.json 内で定義した値を参照できます。

もう 1 つの特徴として、ここで定義した変数は Guide の設定パネルに表示されます。
設定パネルとは、テーマ右下の「カスタマイズ」を選択したときに開くこの画面のことです。

たとえば、manifest.json で次のような設定オブジェクト、変数オブジェクトを定義した場合

manifest.json

"settings": [
  {
    "label": "test_group",
    "variables": [
      {
        "identifier": "test_color",
        "type": "color",
        "description": "test_color_description",
        "label": "test_color_label",
        "value": "#FFFFFF"
      }
    ]
  },
  ...

設定パネルにはこのように表示されます。

設定オブジェクトごとに設定パネル内のグループが 1 つ追加され、グループ内の変数オブジェクトごとに値を設定する UI が追加されるというわけです。

設定パネルで行った変更は manifest.json で定義したデフォルト値を上書きします。これにより、リリース後に GUI で直接変数の値を更新できます。

manifest.json や設定オブジェクトについて、詳細は公式ヘルプの
テーマの「設定」パネルのカスタマイズ
をご参照ください。

更新時の「テーマ設定を維持する」オプション

変更をリリースする というステップのところで、「GitHub から更新」を選んだ際のダイアログに「テーマ設定を維持する」というオプションがありました。

これは「設定パネルに表示されている各種変数の値を manifest.json の値で更新するのか、それとも現在の設定値を維持するのか」を決定するものです。

上述したように、設定パネルの値はリリース後に GUI 上で更新できるため、ここで加えた変更をリポジトリ側の内容で上書きしてしまわないように、という意図だと思われます。
しかし、manifest.json に定義されている値との乖離を許容することになるので運用上は注意が必要です。

また、デフォルトでチェックボックスは ON になっている、すなわち manifest.json の値を反映 "しない" 挙動になっていることも注意です。

ZCLI でテーマを更新できないの？

手順では最後のリリースのステップを画面上から行っていましたが、実は ZCLI にもテーマの更新用のコマンドが存在します。
https://github.com/zendesk/zcli/blob/master/docs/themes.md#zcli-themesupdate-themedirectory

ただし、今回紹介した手順で作成したテーマに対し、このコマンドを実行すると失敗します。

# themeId は `zcli themes:list` を実行するとわかる
$ zcli themes:update --themeId=<theme id>
Creating theme update job... !
 ›   Error: NonUpdatableTheme - Only themes with origin `api` are allowed

これは、API によるテーマの更新は、同じく API を使って作成されたテーマに対してのみ実行できる という制限があるためです。
（一応、API ドキュメントに該当のエラーコードは記載されていますが、そういう仕様であることはサポートに問い合わせて判明しました）

そのため、テーマの更新も CLI で行いたい場合、GitHub 連携機能は使わず、最初に themes:import コマンドを使用してテーマを作成する必要があります。

なお、API で作成したテーマかどうかは、テーマ一覧のアイコンを見るとわかります。

おわりに

Guide のテーマを GitHub で管理する方法や注意点などを紹介しました。
git や GitHub のおかげで変更履歴が追いやすくなりますし、ローカルプレビュー機能を使うと毎回デプロイしなくても変更内容が確認できて良いですね。

一方 Tips の最後に書いたように GitHub 連携機能を使うと ZCLI での更新ができなくなるため、「main ブランチにマージしたら ZCLI で本番環境に自動リリース」みたいなことまでやろうと思ったら
GitHub で管理するけど GitHub 連携機能は使わないほうがいいのかも、、、という微妙な感想になってしまいました😅

参考リンク

• GitHub インテグレーションを使用した Guide テーマの設定 – Zendesk ヘルプ
• Guide における GitHub の管理対象のテーマの更新方法 – Zendesk ヘルプ
• テーマに加えた変更をローカルでプレビューする方法 – Zendesk ヘルプ
• Github インテグレーションの Guide テーマに関する問題のトラブルシューティング – Zendesk ヘルプ
• ヘルプセンターテーマのカスタマイズ – Zendesk ヘルプ
  • テンプレート内の *.hbs ファイルについての説明が記載されています
• テーマの「設定」パネルのカスタマイズ – Zendesk ヘルプ
  • manifest.json について詳しい説明が記載されています
• https://github.com/zendesk/zcli/blob/master/docs/themes.md
  • ZCLI の themes コマンドのリファレンス