GitHub ActionsでZennブログの校正を自動化してみた
概要
前回の記事でも紹介したとおり、ZennはGitHubリポジトリと連携すると、自分の好きなエディタで記事を書くことができます。
そこで今回はGitHub Actionsとtextlintとreviewdogを使うことで、PRするたびに自動でドキュメント校正をしてくれるCI環境の構築をしてみました。
ドキュメント校正ツール
今回GitHub Actionsに組み込む校正ツールは以下の2つを使用します。
- textlint
- reviewdog
それぞれのツールについて簡単にはなりますが、紹介いたします。
textlint
textlint
はMarkdown形式やプレーンテキストのファイルを校正してくれるJavaScriptで記述されたOSSツールです。
textlintはデフォルトルールというものが存在せず、自分でルールの設定とプラグインが必要になります。
ルールの設定箇所は.textlintrc
ファイル内に記述します。
{
"rules": {
"preset-ja-technical-writing": {
"sentence-length": false,
"ja-no-weak-phrase": false
},
"prh": {
"rulePaths": [
"node_modules/prh/prh-rules/media/WEB+DB_PRESS.yml"
]
}
}
}
ここでは2つのルールをセットしてあります。
- textlint-rule-preset-ja-technical-writing
- textlint-rule-prh
textlint-rule-preset-ja-technical-writing
は技術文書向けのルールプリセットです。
ルールプリセットは複数のルールを1つにまとめたルールで、textlint-rule-preset-ja-technical-writing
は以下のルールが含まれています。
- 「ですます調」、「である調」を統一します
- 同じ助詞を連続して使用しない
- 一文の長さは90文字以下とする
ただ、文字数の縛りはURLを文中に貼るとURLの文字もカウントしてしまい、PRの承認がうまくいかないときもありましたのでfalse
にしました。
ほかにも、「〜だと思います」という弱い日本語表現は技術書でしたら使わないようにしますが、ブログですのでそこまで厳しくしなくても良いと判断して、同じくfalse
にしています。
textlint-rule-prh
は表記ゆれをチェックしてくれる校正補助ツールです。
たとえば、りんごが箱の中に有った
という文でしたら、有ったという文をあったに変換してくれます。
2021/4/10追記
Smart HRさんが新しくルールプリセットを作成して、外部に公開してくれたようです。
参考記事⇓
GitHub⇓
私の校正ルールに合いそうだと思いましたので、.textlintrc
の中身を変更しました。
textlint-rule-prh
の独自辞書の中身も公開してくれましたのでこちらも使ってみました。
みなさんが使う場合は、ローカルのPCにSmart HRさんの辞書を格納しておいてください。
(私はdictディレクトリを作成してその中に置きました)
reviewdog
reviewdog
はtextlintなどLinterツールの結果を、GitHubのPRにレビューコメントを投稿してくれるGoで記述されたOSSツールです。
紹介した2つのツールを使うことで、ローカルで書く→git push
→PRする→GtiHub Actionsが動くというCIが構築され、自動でドキュメントの校正が始まります。
それではGitHub Actionsのワークフローファイルの中身を紹介していきます。
中身について解説します。
ワークフローファイル解説
大まかなステップの流れとしては次の通りです。
- reviewdog,nodeのアクションを起動
- textlintのインストール
- textlintを記事に対して実行
- 何かしらの記載ミスが有った場合のみtextlintの出力結果をreviewdogに渡してGitHubにレビューコメントを投稿
工夫した点としてcacheアクションを使うことで、ワークフローの高速化を図りました。
ところがGitHub Actionsが提供しているactions/cacheですが、stepsが失敗しているとキャッシュを取得しないという仕様があります。
この仕様のおかげでドキュメントを校正し、textlintで記載ミスがあるとキャッシュを取得してくれず、毎回textlintのインストールを最初からインストールし直します。
調べてみると有志でactions/cache
をforkしてstepsが失敗してもキャッシュを取得するようにしたアクションを公開してくれる人がいましたので、それを使うことにしました。
これでstepsが失敗してもキャッシュを取得してくれてワークフローの処理を速めることができました。
キャッシュ取得前
キャッシュ取得後
またtextlintで特に問題が見つからない場合、reviewdogを実行するのは無駄なstepsになりますので、if: failure()
で前述のtextlintで異常が見つかった場合のみ実行するようにしました。
デモ実行
実際にgit push
してdevelop
ブランチからmain
ブランチにPRし、何かしらの表現ミスがありましたら、reviewdogがこのようにレビューコメントを出してくれます。
こんな感じで、PRしてgit push
するたびにGitHub Actionsが動いてドキュメント校正してくれます。
1個前の記事からリポジトリで記事を管理しましたので、そちらもtextlintをかけてみましたが、結構指摘箇所がありました。
所感
もともとCircleCI実践入門本でつまずいた部分でしたが、知り合いの力を借りて何とか解決できたところです。
(詳細はこちらのスクラップ参照)
身近でCIを試せるものはないかと検討して、ブログ記事の自動校正化にチャレンジしてみようと思いました。
まだ記事のリポジトリ移管が進んでいませんが、移管後にドキュメント校正をして、ついでに文章の見直しをしようと思います。
LT資料
LTのスライド資料です。
参考文献
Discussion
こちらの記事を参考にさせて頂きましたありがとうございます🙏
GitHub Actionsにて同様な設定をした際にreviewdogによるコメントがされないのですが、何か思い当たる節ありますでしょうか?
私の記事をご覧いただきありがとうございます。
reviewdogの仕様なのか一度の実行で大量にエラーがある場合、GitHub botにコメントがあらわれないようです。
私はデバッグ目的で
Run reviewdog
ステップ内で直接ログの中身を見て確認できるようにしています。Yokiさんのワークフローファイルを確認しましたが、私と同じように
cat
でログを参照していましたので、ステップの中身を確認しましたが、大量にエラーが出ていました。エラーの出力はxml形式なので適当にメモ帳にコピーして
.xml
形式で保存すればエラーの中身が見れます。いくつかエラーを修正してもう一度pushすればreviewdogでコメントが投稿されると思いますのでお試しください。