Cntlog

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