Zendesk GuideのテーマをGitHubで管理する
株式会社ログラス CRE(Customer Reliability Engineer)の @zaki___yama です。
弊社ではユーザー向けヘルプサイトの構築に Zendesk (https://www.zendesk.co.jp/)の Guide 機能を使用しています。Guide にはテーマのカスタマイズ機能があり、たとえば全体的な色味を自社のブランドカラーと合わせたり、テンプレートをカスタマイズすることでデザインだけでなく機能を拡張することが可能です。
弊社でもこれまで Guide のテーマには何度か軽微なカスタマイズを加えてきましたが、すべて管理画面から直接行っていました。
その結果、どういった経緯で・どういうカスタマイズを加えたのか、という歴史的経緯を紐解くのが難しい状態になっていました。
幸い Guide のテーマは GitHub との連携機能を提供しており、これを機に GitHub での管理を試してみました。
環境構築の手順や注意点を紹介します。
GitHub 連携をはじめる手順
GitHub リポジトリにテーマを準備する
まずは、管理対象となる GitHub リポジトリを作成し、テーマを準備します。
Guide のテーマ管理画面(https://***.zendesk.com/theming/workbench
)にアクセスし、管理したいテーマのメニューから「ダウンロード」を実行します。
そして、ダウンロードしたファイルを GitHub のリポジトリにコミット・プッシュしておきます。
別の方法として、Zendesk の標準テーマ(Copenhagen)は GitHub のリポジトリでも公開されています。
このリポジトリを fork して始めるという方法もあります。
ただし、CI やビルド関連など、テンプレートそのものには必要ないファイルも含まれています。
Zendesk で GitHub 連携を設定する
準備したリポジトリを Zendesk と連携します。
Guide のテーマ管理画面から「テーマを追加」>「GitHub から追加」を選択します。
あとはダイアログに従い、準備したリポジトリのユーザー名・リポジトリ名、およびブランチ名(任意。省略するとデフォルトのブランチ)を入力します。
成功すると、テーマライブラリにテーマが追加されます。
これで、テーマを GitHub リポジトリ上でカスタマイズする準備が整いました。
ローカル環境でテーマ変更をプレビューする
Zendesk CLI(ZCLI) を使うと、ローカルでファイルを変更した結果を Zendesk Guide 上でプレビューできます。
ZCLI については以前別の記事でも紹介したので、こちらの記事のインストールおよび認証の項を参考にしてください。
認証まで済んだら、リポジトリのルートで 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
)内のバージョン番号を更新します。
{
"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 で確認)
{
"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 ファイル内で
.blocks-item-internal a {
color: $text_color;
}
のように書くことで、値を直接書かずに manifest.json
内で定義した値を参照できます。
もう 1 つの特徴として、ここで定義した変数は Guide の設定パネルに表示されます。
設定パネルとは、テーマ右下の「カスタマイズ」を選択したときに開くこの画面のことです。
たとえば、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
コマンドのリファレンス
- ZCLI の
Discussion