社内のミーティングを支えるGitHubのIssue自動作成ツールを拡張した話

こんにちは。WantedlyでBackendエンジニアをしている新卒の山岸です。Wantedly Peopleで半年開発を経て今はWantedly Visitの開発をしています。

これはWantedly 新卒 Advent Calendar 2021の記念すべき1日目の記事です！今年の新卒は5人のエンジニアのみです。このアドベントカレンダーはこの5人でまわして25日間を走り切る予定です。

「え、そんな無茶な、、、」

そう思いましたよね、今。しかし我々にはありあまるほどのエンジニアリングに対する好奇心と熱意と最後に若さがあります。我々5人はこの重圧に屈することなく最後までお互い助け合って走り切ると誓いました。「アウトプットこそ最大のインプット」、これを胸に自分たちの学びのためにもこの25日間エンジニアリングに没頭します！

5人とも別々の背景を持って入社してきた精鋭(？)なので内容的には幅広く提供していくつもりです！コンパイラーの話からアルゴリズム、推薦モデルの話まで多くの話題が用意されつつあります。ぜひ最後までお付き合いください！

今日は最初の話としてWantedlyの社内ツールissue-creatorにGitHub Discussionsの機能を拡張した話をします。

WantedlyではGitHubを中心にコミュニケーションをとっています

エンジニアのみなさんの中でGitHubを開発用のコードホスティングプラットフォームとして普段から使う方は多いと思います。 WantedlyでもGitHubを開発初期から使用しており、コードをバージョン管理する場として使うだけでなく、プロダクトに関わるコミュニケーションの場として使い倒しています。 プロダクト開発では仕様の定義や実装方針、実際の実装やその結果分析など様々なデータとそれに付随するコミュニケーションが生まれます。 Wantedlyではそれらの情報にいつでもどこからでもたどり着けるようにドキュメンテーションの意味も込めてIssueやPRに残すようにしています。

また、GitHub上のコミュニケーションは非同期コミュニケーションを行う場としても優秀です。 コロナ禍でリモートワークをすることも多くなったと思います。 リモートワークではすぐその場で相談するという同期的コミュニケーションが難しくなり、Slackなどのチャットツールを使って非同期な情報共有が多くなりました。
GitHubにも通知機構があるので、それをうまく活用することで必要な情報を好きなときに得ることができ、これによって作業に集中することができます。 GitHubの通知とその生産性の親和性については研修でも取り上げられており、詳しくはこちらも見てみてください。

issue-creatorとは

ここまででWantedlyが如何にGitHubを使い倒しているかがわかったと思います。 issue-creatorはそんなGitHubでのコミュニケーションを加速させる単純明快なツールです。 一言でいうと定期的にissueを作ってくれるCLIツールです。

ミーティングの中でも定期的に行われるものがあると思います。 それは毎週のチームのKPTかもしれないし、毎月のチーム外との進捗を共有する場かもしれません。 もちろんWantedlyではその内容もGitHub上に残します。 issue-creatorは定期的なミーティングのためのIssueを自動で作ってくれるというものです。
作った当時のストーリーがあるのでこれを見てみることでモチベーションなどをしることができます。

GitHub Discussionsの機運

従来のissue-creatorはIssueを定期的に作ってくれるというものでした。 それでも十分便利だったのですが、2021年8月からGitHub Discussionsがβ版から正式リリースされ多くのOSSでも議論の場として使われるようになり、issue-creatorにもその需要が高まっていました。

↑ 実際にGitHub Discussionsのfeedbackの場としてGitHub Discussionsが使われている例

本来、会話はリスト構造ではなくツリー構造で表せるデータ構造をしています。 SlackやTeamsなどのチャットツールでもスレッドが建てれるようになっており、その機能がなければ人数が多い場では会話が成り立たなくなってしまいます。

Issueでも同じことが言えて、複数人が絡んでくるとコミュニケーションが取りづらくなるという問題がありました。 その問題をGitHub Discussionsでは、コメントに対してスレッドが建てれるようにしたことで解決しています。 詳しい機能はドキュメントを見てみると色々な使い方が書いてあります。

Wantedly社内でもβ版のころから広く知見共有や質問の場として使われており、その有用性は認知されるものとなっていました。

GitHub Discussionsはissue-creatorの考え方からも欲しい機能でした。 特に複数のチームが進捗や知見を共有するミーティングには最適です。 そのようなSyncUp系のミーティングは事前に情報を各チームがまとめてミーティング中に発表していき、それぞれ議論を展開することが多いのでGitHub Discussionsのコメントとそれに対するスレッドがある形式にピッタリです。 今回はその需要からissue-creatorにGitHub Discussionsも作れるような機能を拡張しました。

拡機能の実装

前置きが長くなりましたが、いよいよ実装の話をしていきたいと思います。 issue-creatorの設計がどのようなものか説明しつつ今回どのような変更を行ったのかを説明していきたいと思います。

issue-creatorはCLIツールとして実装されています。
やりたいこととしては次のようなコマンドを叩いてGitHub上にIssueを作ることです。

# issue-creator create <tempalte issue url>
issue-creator create https://github.com/rerost/issue-creator/issues/1

まず、テンプレート用のIssueを作っておいてそのURLをコマンドに渡せばテンプレートから内容を生成してIssueを作れます。テンプレートの例は以下のようなものです。

テンプレートIssueには変数を入れ込めるようになっていて、作成時点の日付や前回作成したリンクなどを自動で注入できるようになっています。

Issueを定期的に作成することはissue-creatorの責務ではありません。 実際にはKubernetesのCronjobやGitHub Actionを使って作成できるようにサポートしています。 issue-creatorのフローを図で表現すると以下のようになります。

引用: https://github.com/rerost/issue-creator

中身の設計自体はそれほど難しくありません。
手順を簡単に書くと以下のような動きをします。

1. テンプレートIssueの内容を取得する
2. 内容の変数の部分に値を注入する
3. テンプレートIssueと同じリポジトリに2でレンダリングした内容でIssueを新規に作成する
4. CloseLastIssueオプションがついている場合は前回のIssueを探してきてCloseする

これらはGitHubのAPIを使えばそれほど複雑な処理にならずに実現可能な機能でした。 ただ、設計自体はしっかり依存関係が考えられていて複数のレイヤーにわかれています。 具体的には図のような依存関係になっています。

それぞれの責務は以下のようなものです。

• issue model: 根幹となるIssueのドメインモデルを管理するものであり、具体的には型定義をしている部分
• issue repository: IssueをGitHubから取得したり作成したりして、モデルデータを外部とやり取りする部分
• issue service: コマンドのビジネスロジックを集約する場所で、repositoryとのやり取りとその順序が書かれている
• cmdはコマンドを管理するレイヤー

今回はこのような設計にGitHub Discussionの機能を加えます。
まず、実装当時まだβ版だったことからミニマムの実装方針で進めることになりました。 というのもまだまだ機能が増えて破壊的な変更を伴う可能性もあったので、その際にIssueを作ることさえできなくなってしまったら困るからです。 ミニマムで考えた結果Discussionsに関するロジックは分散させることなく1つに集約する設計にしました。
今回の実装で次のような依存関係になりました。

Discussionsのロジックをdiscussion repositoryに集約にすることでDiscussionsのロジックをすぐに切り捨てることもできるようになっています。

また、分割した部分をrepositoryレイヤーにしたことには以下のような事情がありました。

1. コマンドは今までと同じインターフェースで提供したい
2. GitHubをたたくAPIの種類がIssueと異なる

今までのコマンドは先述したように以下のようなものでした。

# issue-creator create <tempalte issue url>
issue-creator create https://github.com/rerost/issue-creator/issues/1

これをDiscussionsに適用したときにDiscussions用のオプションを追加するということもできますが、ユーザーから見たときに同様のインターフェースを提供した方が使いやすいと考えました。
それゆえ、DiscussionsのときもテンプレートDiscussionを作って同じ用にコマンドに与えることで内部で判別してあげるということになりました。

# issue-creator create <tempalte discussion url>
issue-creator create https://github.com/rerost/issue-creator/discussions/48

また、IssueはGitHub REST APIで提供されているのに対して、DiscussionsはGraphQL APIでしかAPIが提供されていません。 Issueの方はREST APIを使って実装されていたので、アクセスの仕方が変わってきます。
Issueの方もGraphQLを使った実装に移行するという話もできますが、今回はミニマムの変更ということでrepositoryレイヤーで分割し、それぞれでAPIアクセスは定義するようにしました。

細かい内容は実際に拡張した際のPRから見ることができます！

まとめ

今回はWantedlyにおけるGitHub上のコミュニケーションの生産性を上げるissue-creatorの魅力とそこにGitHub Discussionの機能を追加した話をしました。GitHub Discussionsの需要の高まりから始まり、issue-creatorに機能を追加したことでより生産性の高いミーティングができるようになりました！

issue-creatorはOSSなのでぜひ使用・コントリビュートしてみてください！

アドベントカレンダー頑張るぞー！🎄