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
と記載して配置すると空白のテンプレートは選べなくなります。
原因と対処法
考えられる原因はいくつかあります。一つずつ確認していきましょう。
- ファイル名が間違っている:
- 原因:
.github/ISSUE_TEMPLATE.md
というファイル名が正確でない。大文字・小文字、スペースの有無など、少しでも違うと認識されません。 - 対処法: ファイル名を
.github/ISSUE_TEMPLATE.md
に正確に修正する。
- 原因:
- ディレクトリ構造が間違っている:
- 原因:
.github
ディレクトリの中にISSUE_TEMPLATE
ディレクトリを作成し、その中に.md
ファイルを配置する必要があります。 - 対処法:
.github
ディレクトリを作成する (存在しない場合)。ISSUE_TEMPLATE
ディレクトリを作成する (存在しない場合)。.md
ファイルをISSUE_TEMPLATE
ディレクトリ内に移動する。
- 原因:
- 複数テンプレートが存在する場合 (これが盲点!)
- 原因:
.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形式で記述します。(下記参照)
- 単一テンプレートに戻す場合:
- 原因:
- テンプレートファイル(.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テンプレートが適用されない問題は、ファイル名やディレクトリ構造のミス、複数テンプレートの存在などが原因であることが多いです。 今回の備忘録が、同じ問題で困っている方の助けになれば幸いです。