GitHub issuesにストーリーポイントを振ってプロジェクトの進捗を可視化する with Next.js

プロジェクトの進捗状態を可視化するツール storyteller を作成しました。

GitHub issuesなどをソースとして、スプリント単位でのストーリーポイントの平均消化速度などを表示できます。Web上で出力サンプルを確認できます。

本記事では、このツールのデザインと実装について紹介します。

あまり手間をかけずに進捗を可視化したい

storytellerは、大まかには以下を行うだけのツールです。

1. GitHub APIを用いて、リポジトリのissuesを取得する
2. リポジトリの各issueをプロジェクトのタスクに見立てて、issueのcreate/closeを時系列順に並べる
3. 時系列順のデータを元に、スプリント単位のストーリーポイントの平均消化速度などを計算・可視化する

このようなデザインの背景には、本格的なタスクと進捗管理に優れたサービスは既に存在する ^[1] ということが挙げられます。storytellerは、GitHub issuesからなるべく手間をかけない形で、プロジェクトの進捗状態を「issuesのopen/closedの割合」より一歩進んで可視化できないかと考え作成しました。

GitHubのissuesにはストーリーポイントのような値を設定する機能はありません。これについてもなるべく手間がかからないように、storytellerでは sp:XXX という名前のラベルをストーリーポイントとして解釈するようにしました。 (未指定の場合はデフォルト値が採用されます)

Next.jsによるStatic Site Generation

storytellerの目的は進捗の可視化であり、write系の操作は一切ありません。また、プロジェクトの進捗の可視化にはリアルタイム性も重要ではありません。このような要件には静的サイトジェネレータの活用が考えられます。静的サイトであれば、(Private) GitHub Pagesを用いて、メンバー間に進捗を共有することも容易です。

ということで、storytellerでは実装にNext.jsのStatic HTML Exportを採用しました。
storytellerの実行ステップで挙げた「GitHub APIを用いて、プロジェクトのissuesを取得する」は、実際には以下のような流れで実現されています。

1. npm run build によって next build が始まる
2. Next.jsによって getStaticPaths / getStaticProps が呼び出される
3. これら関数をエントリポイントとした処理の中で、 child_process を用いてGitHub CLIの gh api を呼び出す

GitHub Actions等によるビルド中に呼び出される、というコンテキストを考慮して、storytellerではGitHub CLIを利用しています。GitHub Actions上であれば、 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} のように環境変数にトークンを与えることで、Zero-configurationでGitHub APIを利用できます。

所感とハマりどころいくつか

Next.jsによるSSGは、大まかには通常のNext.jsでラクなところは変わらずラクで、この規模ではあまりハマりどころ無く開発することができました。静的サイト生成時に動作するプログラムは一般的なNodejsアプリケーションなので、CI等と組み合わせると他にも用途を見出せそうです。

とはいえ何点か気を付ける点はありました:

• next/image は現状利用できない: 通常の img タグを使用する
• Project GitHub Pagesのように非ルートに生成結果が配置される場合は、next.config.jsに追加の設定が必要
  • img タグのsrcについても同様
• next.config.js でstaticPageGenerationTimeout を設定しておく

脚注

1. ClickUpとか