GitHubのIssueテンプレート(.github/ISSUE_TEMPLATE.md)が適用されない時の対処法

GitHubでリポジトリにIssueテンプレートを設定したのに、新規Issue作成時にテンプレートが適用されない…！そんな困った経験はありませんか？
私も先日、以前Issueテンプレートを設定したものが、うまく適用されずに焦りました。

この記事では、.github/ISSUE_TEMPLATE/**.md が適用されない場合の原因と対処法を、備忘録としてまとめました。

まずは解決方法

• 全角でISSUE_TEMPLATEを作いた場合半角に変更することで解消します。
• .github/ISSUE_TEMPLATE.mdを.github/ISSUE_TEMPLATE/issue_template.mdのように配置変更する

補足：直接の原因とは異なりますが、空白のテンプレートを使わせたくない場合は.github/ISSUE_TEMPLATE/配下にconfig.yml を設置して、blank_issues_enabled: false と記載して配置すると空白のテンプレートは選べなくなります。

原因と対処法

考えられる原因はいくつかあります。一つずつ確認していきましょう。

1. ファイル名が間違っている:
   • 原因: .github/ISSUE_TEMPLATE.md というファイル名が正確でない。大文字・小文字、スペースの有無など、少しでも違うと認識されません。
   • 対処法: ファイル名を .github/ISSUE_TEMPLATE.md に正確に修正する。
2. ディレクトリ構造が間違っている:
   • 原因: .github ディレクトリの中に ISSUE_TEMPLATE ディレクトリを作成し、その中に .md ファイルを配置する必要があります。
   • 対処法:
     • .github ディレクトリを作成する (存在しない場合)。
     • ISSUE_TEMPLATE ディレクトリを作成する (存在しない場合)。
     • .md ファイルを ISSUE_TEMPLATE ディレクトリ内に移動する。
3. 複数テンプレートが存在する場合 (これが盲点！)
   • 原因: .github/ISSUE_TEMPLATE/ ディレクトリ内に複数の .md ファイルが存在すると、単一のテンプレートは適用されません。GitHubは複数のテンプレートファイル(issue_template.mdやbug_report.mdなど)がある場合、Issue作成時にテンプレートを選択する形式になります。
   • 対処法:
     • 単一テンプレートに戻す場合:
       • 不要な .md ファイルを削除し、.github/ISSUE_TEMPLATE.md だけを残す。
     • 複数テンプレートを維持する場合:
       • .github/ISSUE_TEMPLATE/ディレクトリ内に複数のテンプレートファイル(.md)を配置する。Issue作成時にテンプレートを選択できるようになります。
       • 各テンプレートファイルには、name, about, title などのメタデータをYAML形式で記述します。(下記参照)
4. テンプレートファイル（.md）内のYAMLフロントマターの記述ミス(複数テンプレートの場合)
   • 原因: 複数テンプレートを使用している場合、各テンプレートファイルの先頭にYAML形式でメタデータを記述する必要があります。この記述が間違っていると、テンプレートが正しく認識されません。
   • 対処法: 以下のYAMLフロントマターを正しく記述します。
   • -- name: "Bug Report" about: "バグを報告するためのテンプレート" title: "[Bug] " labels: ["bug"] assignees: - "your-github-account" ---
   • name: テンプレートの名前 (Issue作成時に選択肢として表示される)
   • about: テンプレートの簡単な説明
   • title: Issueのタイトルに自動で入るプレフィックス
   • labels: Issueに自動で付与されるラベル (複数指定可)
   • assignees: Issueに自動でアサインされるユーザー (複数指定可)

まとめ

GitHubのIssueテンプレートが適用されない問題は、ファイル名やディレクトリ構造のミス、複数テンプレートの存在などが原因であることが多いです。 今回の備忘録が、同じ問題で困っている方の助けになれば幸いです。