「再現できない」を減らす：GitHub Issueの不具合報告テンプレート

「ボタンが動かない」と報告したけれど、相手の環境では再現しない。そんなときは、説明を長くするより、同じ状態へたどり着く手順と、期待した結果・実際の結果を分けることから始めよう。

この記事では、GitHubのIssueフォームで不具合報告を揃えるための、小さなひな形を用意する。フォームを採用するには、対象リポジトリへの書き込み権限と、Issuesを使える設定が必要。ページ内の練習用作例だけなら、アカウントなしで試せるよ。

最初に集めたい四つの情報

毎回起きるのか、ときどき起きるのかも添えると、試す条件を揃えやすいね。原因がまだ分からないなら、観測したことと推測を別に書こう。

原因を決めつけず、操作を再現できる形にする

たとえば、架空のカウンターの不具合なら、次のように整理できる。

再現手順:
1. 新しいタブでカウンターのページを開く。
2. 初期表示が「押した回数：0」であることを確認する。
3. 「回数を増やす」を1回押す。

期待した結果: 「押した回数：1」になる。
実際の結果: 「押した回数：0」のまま変わらない。
環境: テストしたOS・ブラウザと、その版を記載する。

これは報告の書き方を示す架空の例。このサイトのカウンターに、その不具合が発生したという報告ではないよ。

「JavaScriptが壊れた」と先に断定すると、別の条件を見落としやすい。まずは画面で見たことを残し、エラーメッセージや最小限のサンプルがあれば追加しよう。

GitHubのIssueフォームにする

ダウンロードできるYAMLひな形を、自分のリポジトリの.github/ISSUE_TEMPLATE/bug-report.ymlなどへ置く。既存テンプレートがある場合は上書きせず、名前や用途の重複を先に確認してね。

YAMLは、設定を文字で表す形式。インデントに意味があるので、コピー後に階層が崩れていないか確認しよう。ひな形の入力項目は次のような構造だよ。

name: 不具合の報告
description: 再現手順と期待・実際の結果を整理する
body:
  - type: textarea
    id: steps
    attributes:
      label: 再現手順
      placeholder: |
        1. 最初の状態
        2. 行った操作
        3. 確認した表示
    validations:
      required: true

配布ファイルには、期待した結果・実際の結果・環境の欄も入れている。フォームのrequired: trueは入力を求める指定であり、入力内容の正確さまで自動で検証するものではないよ。

公式資料によると、Issueフォームの回答はMarkdownへ変換され、Issue本文になる。公開リポジトリなら、書いた内容が公開されることを前提に、送信前に確認しよう。説明用のmarkdown項目はフォーム上で表示される案内で、回答としてIssue本文に送信される項目とは扱いが違う。

ページ内の作例で、項目を分ける練習

この記事の下にある「動かしてみよう」では、四つの欄へ架空の内容を入れて「報告文を作る」を押せる。入力が揃うと、コピーして使えるMarkdownを表示するよ。

この作例はGitHubの実際の画面ではなく、編集部の練習用フォーム。入力はブラウザ内で処理し、GitHubへの送信やIssue作成は行わない。実際の秘密情報や顧客データではなく、架空の短い文章で試してね。

編集部では、未入力で生成が進まないことと、四つの欄へ入れた文章が対応する見出しの下へ出ることをブラウザで確認している。YAMLひな形も構文・項目IDの重複・必須欄を確認した。ただし、GitHub上へ導入してフォームが表示されるところまでを実施した検証ではないよ。

導入後は、公開される入口で確認する

公式手順では、テンプレートをデフォルトブランチへ反映すると、Issue作成時に使えるようになる。自分の環境では次を確認しよう。

1. 新規Issueの選択画面に、意図した名前のフォームが出るか。
2. 必須欄と任意欄が、想定した扱いになっているか。
3. 説明、入力例、長い文章の見え方が分かりやすいか。
4. 既存の報告と重複しないか、送信前に検索できるか。
5. 秘密情報やセキュリティ報告を、公開Issueへ書かせる案内になっていないか。

ラベルや担当者の自動設定は、このひな形には付けていない。必要なら公式の仕様と、実際に使えるラベル・権限を確かめて追加してね。

関連する設定の取り扱いはGitHub ActionsのSecretsとVariables、AIが加えた変更の確認はgit diffの使い分けも参考にしてね。