【GitHub】issues のテンプレート作成

はじめに

※6月24日に投稿予定でしたが、GitHub Actions のコードを変更したことで投稿できていなかったので、まとめて投稿します

こんにちは。アメリカ在住で独学エンジニアを目指している Taira です。
現在 railsでアプリ開発中ですが開発に苦戦しながら進めています。
前回の記事の続きで、開発をするうえでこれを導入することでかなり頭がすっきりしたうちの1つに issues のテンプレートがあります。
今回はissuesのテンプレートの作成について記事を書いていきたいと思います

1. テンプレートを置く場所

リポジトリのルートに .github/ISSUE_TEMPLATE/ ディレクトリを作成し、そこにテンプレートファイルを配置します。

.github/
└── ISSUE_TEMPLATE/
    ├── bug_report.yml
    ├── feature_request.yml
    ├── documentation.yml
    ├── test_request.yml
    ├── ci_cd.yml
    └── config.yml

2. 各テンプレートファイルの例

bug_report.yml（バグ報告用）

name: 🐛 バグ報告
description: バグを報告する
labels: ["bug"]
body:
  - type: markdown
    attributes:
      value: |
        バグ報告ありがとうございます。以下の情報を記入してください。

  # 1. バグの説明（description）
  - type: textarea
    id: description
    attributes:
      label: バグの説明
      description: バグの内容を詳しく説明してください
      placeholder: できるだけ具体的に記述してください
    validations:
      required: true
  # 2. 再現手順（reproduction）
  - type: textarea
    id: reproduction
    attributes:
      label: 再現手順
      description: バグを再現するための手順を記述してください
      placeholder: |
        1. '...' に移動
        2. '....' をクリック
        3. '....' までスクロール
        4. エラーが発生
    validations:
      required: true

  # 3.期待する動作（expected）
  - type: textarea
    id: expected
    attributes:
      label: 期待する動作
      description: 本来期待される動作を記述してください
      placeholder: 正常に動作する場合は〜が表示されるはずでした など
    validations:
      required: true

  # 4. 現時点で思いつく原因・解決策（optional_solutions）
  - type: textarea
    id: optional_solutions
    attributes:
      label: 現時点で思いつく原因・解決策（任意）
      description: このバグが発生した原因や修正のアイデアなど現時点で思いついていれば記入してください
      placeholder: この変数がnullの可能性があると思われます、turbo-streamをfalseと明示すると治りそう など
    validations:
      required: false

  # 5. 発生頻度（frequency）
  - type: dropdown
    id: frequency
    attributes:
      label: 発生頻度
      description: このバグがどれくらいの頻度で発生しますか？
      options:
        - 毎回発生する（Always）
        - 時々発生する（Sometimes）
        - 1回だけ発生した（Once）
        - 不明（Not sure）
    validations:
      required: false
   # 6. 利用環境（environment）
  - type: input
    id: environment
    attributes:
      label: 利用環境（OS、端末など）
      description: 使用しているOSや端末の情報（例 macOS 14 / Windows 11 / iPhone 15 + iOS 17など）を記載してください
      placeholder: Windows 11 + Edge, iPhone 13 + Safari
    validations:
      required: false
  # 7. 該当バージョン（version）
  - type: input
    id: version
    attributes:
      label: 該当バージョン
      description: アプリやライブラリ、ブラウザのバージョンなど（あれば）
      placeholder:  v1.2.3、Chrome 125.0.0.1
    validations:
      required: false
  # 8. スクリーンショット（screenshot）
  - type: textarea
    id: screenshot
    attributes:
      label: スクリーンショット・動画（任意）
      description: 問題がわかる画像や動画があれば、ここに貼り付けてください
      placeholder: スクリーンショットをここに貼り付けてください
    validations:
      required: false
  # 9. ログ（logs）
  - type: textarea
    id: logs
    attributes:
      label: エラーログ・コンソール出力（任意）
      description: 開発者ツールのコンソールログやネットワークエラーなどがあれば貼り付けてください
      placeholder:  Uncaught TypeError Cannot read properties of undefined...
    validations:
      required: false

他のテンプレートも同様の構成で作成します。

3. config.yml でテンプレートを選択肢に登録する

以下が実際に使用する config.yml の例です。

blank_issues_enabled: false
contact_links:
  - name: 質問・相談
    url: https://github.com/habitat-hub/board-game-prototype/discussions
    about: バグ報告や機能リクエスト以外の質問・相談はDiscussionsをご利用ください。

# Issue作成時のテンプレート設定
defaults:
  - template: "bug_report.yml"
    name: "🐛 バグ報告"
    about: "バグを報告する"
    labels: ["bug"]

  - template: "feature_request.yml"
    name: "💡 機能リクエスト"
    about: "新機能のアイデアを提案する"
    labels: ["feature"]

  - template: "documentation.yml"
    name: "✍️ ドキュメント改善"
    about: "READMEやガイドなどの文書の改善提案"
    labels: ["documentation"]

  - template: "test_request.yml"
    name: "🧪 テスト改善"
    about: "テストコードの改善や新しいテストケースの提案"
    labels: ["test"]

  - template: "ci_cd.yml"
    name: "📦 インフラ・CI/CD改善"
    about: "Docker、GitHub Actions、AWSなどのCI/CD・インフラに関する提案を記入してください"
    labels: ["ci/cd"]

この設定により、Issues 作成画面でテンプレートを選択できるようになります。

4. 運用を効率化するポイント

• 記入漏れ防止：required: true を活用することで、必須入力を強制できます。
• 自動ラベル付与：テンプレートごとにラベルを指定すれば、分類が自動化されます。
• Discussions の活用：contact_links を設定して、質問・雑談系は Discussions に誘導できます。

5. まとめ

ステップ	内容
1	.github/ISSUE_TEMPLATE ディレクトリを作成
2	テンプレートファイル（.yml）を複数作成
3	config.yml にテンプレートとラベルの定義を記述
4	運用中にテンプレートを見直し、継続的に改善

テンプレートを導入することで、チームの作業効率が飛躍的に向上します。実際、今まで外部サービスのNotionを使用していましたが、issues がテンプレ化されて楽に作成されるようになったことでだいぶ頭が鮮明になりました。
開発経験者は当たり前に使用していると思いますが、まだ使ったことのない(特に独学の方)はぜひ使ってみてください

参考文献

以下の記事をとても参考させてもらいました。
ありがとうございました。