📝

誰でも起票の情報粒度が一定になる（ことを目的とした）Webアプリのデバッグツールを作った

2022/08/07に公開

GitHub

以前から、個人的にあったら良いかもと思っていた物を作ったので紹介です。

作ったライブラリについて

主な特徴として、Webアプリケーション上で直接GitHubにIssueを起票できる機能を付与します。
起票時には、リポジトリに設定されている Issue Templates を選択でき、テンプレートに定義されている担当者やラベルも自動で設定されます。

また同時に、本文に閲覧環境の追記を自動で行い、任意でスクリーンショットの添付^[1]が可能です。

demo

使い方

npm からライブラリをインストール

settings/tokensから、必要なScopeを付与したPAT(Personal access tokens)を発行
任意のjsに下記の処理を挿入

if (process.env.NODE_ENV !== 'production') {
  import('lit-issue-reporter').then(({ createReporter }) => {
    createReporter({
      token: process.env.GITHUB_TOKEN,
      owner: '<GITHUB_USER_NAME>',
      repository: '<GITHUB_REPOSITORY_NAME>',
    })
  })
}

View側の任意の場所に<issue-reporter></issue-reporter>を設置

以降、デフォルトで画面左下に、起票フォームのトグルボタンが表示されます。
フォームに表示しているテキストはi18n対応をしており、UI含むテキストはオプションで一通り差し替え可能です。

なぜ必要だったか

今回、わざわざGitHub以外から起票できる機能を作ったのには、私の環境的なもので下記のような理由がありました。

プロジェクトのメンバー全員（非エンジニア含む）が、開発やGitHubの扱いに慣れているとは限らない
クライアント（お客様）ご確認のタイミングの起票に対し環境情報等のご確認がしばしば発生していた

1点目について、所属先でのプロジェクト管理は主にGitHubとなっており、
UIに慣れていないデザイナー、PM陣も、Issue上で連絡やディスカッションを行っています。^[2]

こういった状況で、対象箇所の記載やスクショの添付有無について、人により内容の粒度にバラつきが出てしまう事が、エンジニアを含みままありました。

独自の運用ルールについてはドキュメント化されていますが、特に外部パートナーの方にとってはそれ自体が単発のコストとなる可能性もあり、こういった点について都度の共有ではなく、ツール側で吸収できればと考えました。

2点目について、前述の利点とも一部重複しますが、お客様とのやり取りにおいては一度、プロジェクト管理ツールやスプレッドシート等に記載頂き、PMまたはエンジニアにより改めて起票を行う方法を取っています。

この時に、URLや要素といった対象の情報や、状況、環境等について、追加のご質問をさせて頂くケースが発生していました。

中でもブラウザのバージョン、OS、解像度といった情報に関しては、別途ご確認頂くなどお手間を取らせてしまう事もある中、閲覧中であればこういった情報は一通り拾えるため、従来から運用していたシートテンプレよりも確実に解決できるのではと考えました。

コンセプトと技術選定

もう5年ほど前になりますが、CEDEC 2017 の開催時期に出ていた「ゼルダの伝説 BotW」にバグが少ない理由の記事中でも紹介されていた、「ZELDA_ERROR」という仕組みからインスピレーションを得ています。

プレイ中、ゲーム内から「投稿」ボタンを押す事でレポート可能なツールを組み込み効率化を行った、といった趣旨のもので、抱えている課題に対しWebでも類似の対応が可能では、と思った事が作成のキッカケでした。

技術スタックに関しては用途の性質上、何らかのFWやライブラリに依存しない前提で考え、Lit で Web Component を使う形としました。

最終的にESModuleとして出力しており、Vanilla JSの他、React, Vueや、Svelte等でも使いやすいよう想定しています。

スクリーンショットに関してはネイティブの MediaStream API を採用する事で、画像化の際に崩れ等が発生しないようにしています。

Issue TemplatesやRepository情報の取得にはGitHub API v4を叩いており、GraphQLの学習を兼ねています。

testは、書けていません、、。

取り扱いの注意点

認証がPATという事でお気づきかと思いますが、今回クライアント完結を条件とした結果、
repo Scopeを持つPATをアプリケーションに埋め込む必要があり、
万一悪意をもった者に抜かれた場合、アクセス権の範囲でリポジトリを操作されてしまう恐れがあります。

こういったセキュリティの懸念を含むため、現時点において制限付きの環境での使用が絶対条件で、
まずは社内の限定された環境で使用し、認証機能が整った段階で使用範囲を広げる事も検討できればと思っています。

認証に関してはGitHub Appsを使用する事でScopeをIssue管理（ソース閲覧不可）に絞ることができそうなため、タイミングがあれば調べてみたいと思います。

終わりに

ワークフロー自体、より良い手段があるかもしれないですが、ツールとしてイメージままの物は無さそうだったため試作的に作ってみました。

夏休で作った走り書きではありますが、もし何かに役立ちそうでしたら使って頂ければ幸いです。
また、ご興味ある方いらっしゃればコントリビュートも歓迎ですので、よろしくお願いいたします。

脚注

GitHub APIv4ではセキュリティ面で画像を直接アップロードする事が難しそうだったため、Data URIとして埋め込んでいます。（これに関しては、正しく調べきれていない可能性もあります） ↩︎
公衆的な意味ではなく、社内においてそういった場合があるという状況を指しています ↩︎