[GitHub]README.mdの目次生成をAction「toc-generator」による自動化で楽しよう

はじめに

リポジトリのReadme.mdを書き上げた後、読み手が把握しやすい様に目次を追加することがありますが、項目がボリューミーになるとその手間も中々大変なものになります。

• それなりにリッチな目次を
• ある程度手抜きしつつ
• かつ自動的に生成する

の三点が実現出来たら良いなと思っていたところ、バッチリ満たしてくれるActionがありました。設定手順と実行前後の違いについてまとめました。

ToC-Generatorについて

toc-generator/README.ja.md at master · technote-space/toc-generator

目次生成に特化したActionです。動作すると目次生成コミットが積まれます。これ以外の機能はありません。使い方はTOC GeneratorのREADME.mdを一通り読むと判るくらいにシンプルです。

on:
  push:
   - master
jobs:
  comment:
    runs-on: ubuntu-latest
    steps:
      - uses: technote-space/toc-generator@v2
        with:
          GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }}

この例は目次生成のみにしていますが、CICDのフローに挟むことも問題ありません。生成した目次はwithにFOLDING: trueを指定することで畳まれるため、長すぎた場合等は設定しておくと親切になると思います。

ToC-Generator実行前

# example 

## description
message

ToC-Generator実行後

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**

- [example](#example)
  - [description](#description)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

# example 

## description
message

注意点

触っていたところ嵌った点です。

権限が不足しているとエラーになります

ToC GeneratorのREADME.mdにて、アクションをトリガーしたい場合にはGITHUB_TOKENkeyにPersonalAccessTokenを利用するように書かれていますが、権限が不足しているとエラーで止まります。

GitHub Actions で提供されるGITHUB_TOKENは連続するイベントを作成する権限がありません。したがって、プッシュによってトリガーされるビルドアクションなどは実行されません。これはブランチプロテクションを設定していると問題になる場合があります。もしアクションをトリガーしたい場合は代わりにpersonal access tokenを使用してください。

止まった場合はスコープが不足していないか確認しましょう。repoにチェックを入れることで問題なくなるはずです。

止まった例

pull-requestでのREADME差分発生に注意

滅多にないとは思いますが、defaultのブランチに入れないまま複数切った作業用ブランチ夫々でToC-Generatorを導入すると、差分衝突の手間が大きくなります。

ToC-Generatorだけを取り入れるブランチをmergeした後で、各作業用ブランチでのToC作成としましょう。

あとがき

GitHubのREADMEはConfluence等と違って目次生成に対応していないのがとても不便だと感じていました。

このActionをCICD用のWorkflowに挟むことでREADME目次の形骸化も防ぎやすくなることと、オプション指定を見ると分かる通り、目次更新コミットのタイトル等も予め設定が可能なため、

• fix
• update
• toc

等、面倒がために適当でわかりづらくなるコミットメッセージになるのを回避できると思います。導入はあっさり完了するので、ToC芸人として生きるのが辛い、などの人には特におすすめです。