こんにちは！エンジニアリングマネージャの 吉成 です。
この記事は SmartHR Advent Calendar 2023 4日目の記事なのですが、実は ANDPAD さんの Advent Calendar 2023 1日目 とまさかのネタ被りです。
この日のために 後回しにしていた 寝かせていたネタだったので、二番煎じとなりますがこのまま出させていただくことにしました 😌
背景
さて、弊社では今年の5月から、各プロダクトチームが週ごとに持ち回りでテックブログを執筆する取り組みを開始しました。 元々は執筆のためのフローは特に整備しておらず、公開までの壁打ちやレビューといったものは有志の方にすべておまかせしておりました。 今年の8月に DevRel の1人目として inao san が入社され 1、テックブログの担当チームやレビューなど諸々の業務を引き継いでいる中で、組織でのはてなブログ運営をGitHub上で行うためのテンプレートリポジトリ「HatenaBlog Workflows Boilerplate」を公開しました という記事を紹介してくださりました。
この Workflow はとても素晴らしいもので、まさに弊社が求めているものだったため、検証を進めていました。 今回の記事は検証の結果 GitHub を通してレビュー・公開がされる初めての記事となっています。
そもそもなぜ今まで GitHub で管理していなかったのか
記事をはてなブログで管理しているから、と言ってしまえばそれまでなのですが、なぜ GitHub Pages などでブログを作っていないかを補足しておきます。 弊社のテックブログですが、掲載されている記事は幅広い領域にまたがっており、プロダクトエンジニア以外にも QA エンジニアや UX ライター、PdM と様々な職種の方が執筆しています。 プロダクトエンジニア以外の方々は、必ずしも GitHub の使い方や git という概念に慣れ親しんでおらず、すべてを GitHub で管理してしまうと執筆ハードルが不必要に高くなってしまうと考えていました。
そういった方々の執筆ハードルはそのままに、プロダクトエンジニアとしては慣れ親しんだ GitHub でのレビューフローを取り入れられるといった点で、今回の Workflow は求めていたものと一致したと言えます。
環境整備で困ったこと
基本的には hatena/Hatena-Blog-Workflows-Boilerplate の README 通りに設定を行っていけば良いが、いくつか躓いた点があったので紹介します。
なお、このあたりの環境整備自体は 10月に完了していたため、現在のドキュメントでは問題なく進められる可能性もありますのでご承知おきください。
独自ドメイン関係
BLOG DOMAIN の設定
弊社は独自ドメインを利用してブログを公開しています。この場合に BLOG DOMAIN の設定を誤っていることで draft push などの GitHub Actions で失敗してしまう事象に悩まされていました。
ユーザネームやドメインの設定を行う blogsync.yaml や GitHub リポジトリの設定で必要な BLOG DOMAIN ですが、ここは 独自ドメインではなくはてなブログ取得時のドメイン を設定するようにしてください。
なお、この記述は現在わかりやすく修正されているようです。 2
公開URLやカテゴリーを指定したい場合
Workflow を利用して記事を作成すると、md ファイルの最上部に以下のようなメタデータが追記されます。 ここに要素を追加することで記事にカテゴリーを指定できるようになります。
--- Title: テックブログを GitHub で管理できるようにしました EditURL: https://blog.hatena.ne.jp/smarthr/smarthr.hatenablog.com/atom/entry/xxxx Draft: true ---
Workflow では GitHub Actions の利用時に内部的に x-motemen/blogsync: Push and pull blog entries from/to local filesystem を利用しており、以下の6つに対応しているようです。
- Title: タイトル
- Date: 投稿日時
- URL: URL。※自動的に付与されるため、書き換えても効果はない
- EditURL: AtomPub の編集用 URL
- Category: カテゴリ
- Draft: yes のときに下書きとして扱われる
今後のフローについて
今まで GitHub 管理していなかった理由の説明で述べた通り、弊社のテックブログは様々な業種の方が執筆してくれることで成り立っています。 そのため、今のところ GitHub 経由に絞ることは考えておらず、今まで通りはてなブログの管理画面から直接投稿することも許容し続ける予定です。
今後やりたいこと
今回の記事が初の Workflow 経由ということで、まだまだ「GitHub 経由で書けるようにした」だけの状態です。 より便利に活用できるように、今後は以下のようなことを取り入れられないかなと考えています。
textlint の導入
textlint-rule-preset-smarthr を導入し、レビュー時に textlint を通すことで執筆者が文書を書く際に考えることを減らしていきたいなーと思っています。
リポジトリを公開したい
弊社では プロダクトエンジニア向けの採用サイト を GitHub 上で管理しているだけでなく、 リポジトリ も公開しています。 ありがたいことに年に数回、採用サイトを見た社外の方から typo の修正 PullRequest や要望の issue を立てていただくことがあります。 テックブログも同様にオープンにしていくことで、typo だけでなく、例えば誤っている技術的な記載に対する指摘や、「こんな記事を読んでみたい」と言った要望を広く募っていけないかなと妄想しています。
we are hiring
SmartHRでは引き続きエンジニアを絶賛募集中です！少しでもご興味を持っていただけたら、カジュアル面談やOnline Meetupにぜひお申し込みください！
