GitLab CI/CDで研修業務を自動化した話（前編）〜Asciidoctor PDFとDockerによるテキストPDFのビルド〜
こんにちは！
私はカサレアルでラーニング・サービスを担当している山本 薫と申します。
弊社の研修コースで使用している教材の開発や研修環境の準備作業をどのように自動化しているかについて紹介します。
今回は前編として、Asciidoctor PDFとDockerによるテキストPDFのビルドについてお伝えします。
背景
はるか昔、弊社では研修コースで使用するセミナーテキストの開発にMicrosoft WordとPowerPointを使用していました。
そのセミナーテキストは、PowerPointで作成したスライドをWordのドキュメント内に貼り付け文章による説明を記述したものなのですが、自動化と言ってもスライドの貼り付けにマクロを使用している程度でした。
セミナーテキストやサンプルコードなどの教材一式は当時はSubversionでバージョン管理を行っていましたが、WordやPowerPointのファイルは差分が取りにくく、ブランチの運用も困難なものでした。
また、テンプレートを利用して書式を統一したものの、改訂を続けるうちに書式が崩れたり、テンプレートを適切に使わない人が出てきたりと、徐々に統一感がなくなっていきました。
そこで「内容はプレーンテキストで記述し、書式は別の方法で統一しよう」と、Word+PowerPointの仕組みを抜本的に見直すことになりました。
Asciidoctor PDFの採用
プレーンテキストで記述しても、そのままでは研修で使用できません。
印刷・製本した際、少なくともWordテキストと同じくらい読みやすく見栄えが良くなければならないのです。
プレーンテキストをPDFなどの印刷可能な形式に変換するにあたって、世の中には様々な記法やツールが出回っています。
以下は、2016年頃の調査時点で主流だった記法・ツールです。
- Markdown + GitBook
- 記法は広く普及しており派生も多いが書籍としての表現力は低い
- AsciiDoc + Asciidoctor PDF
- 記述の負荷と表現力のバランスが良い
- Re:VIEW
- 日本語に対応しており表現力が高いが利用者が少ない（ほぼ国内？）
- DocBook + Apache FOP
- XMLのため記述の負荷が高く、テンプレート作成の難度も高い
検討の結果、書きやすさと表現力のバランスが良いと感じたAsciiDoc + Asciidoctor PDFを採用しました。
Dockerを利用したPDFの生成
Asciidoctor PDFはRubyというプログラミング言語で記述されているため、Rubyの実行環境が必要です。また、Asciidoctor PDF本体のほか、画像の埋め込みやコードのシンタックス・ハイライトを行うためのプラグインをインストールしたり、共通のテンプレートを配置する必要があります。
弊社にはテキスト開発を行うメンバーが複数名いるため、それぞれが利用しているコンピューターにテキスト開発環境を構築し維持するのはとても手間がかかります。しかも、Windowsを利用しているメンバーもいれば、Macを利用しているメンバーもいて、とても面倒をみきれません。
そこで目をつけたのが当時普及し始めていたDockerです。
Dockerは、オペレーティングシステムから隔離した環境でアプリケーションを実行します。
つまり、WindowsでもMacでも、Dockerさえインストールしていれば、コマンドを実行するだけでAsciidoctor PDFを使ってPDF変換が実行できます。
これで個人のテキスト開発環境は準備できました。
＜関連コース＞
GitLab CI/CDによる教材ビルドの自動化
Asciidoctor PDFを導入すると同時に、バージョン管理システムもSubversionからGitへと移行しました。
Gitへの移行にあたり、リモート・リポジトリの管理にどのサービスを利用するか検討しました。
当初からGitHubかGitLabかの二択だったのですが、使い勝手の良さやライセンス形態が私たちのニーズに合致しているという理由のほかに、GitLab CI/CDとしてビルドパイプラインの実行が標準提供されていることが決め手でGitLabを採用しました。
今でこそ、GitHubもGitHub Actionsを提供していますが、当時はJenkinsなどの外部システムと連携する必要があったのです。
テキストのAsciiDoc化やGitLabの導入により、本格的なブランチ運用ができるようになりました。
大まかな流れとして、
- 研修実施の際に見つけた誤植などはイシューとして起票し、ブランチで修正したのちにマージリクエストを利用してレビュー＆マージする
- プッシュやタグを作成するタイミングで、ビルドパイプラインを実行し、テキストのPDF変換やサンプルコードのZIPファイルへの圧縮を行いビルド成果物として保管する
- 研修実施の際には各研修環境にビルド成果物を配布する
といったワークフローの自動化が確立しました。
＜関連コース＞
今回のお話はここまでです。
次回は後編として、AWSとTerraformによるcode-server環境の構築についてお伝えします。
