GitHub Issues（イシュー）とは、プロジェクトのタスク・バグ・質問・アイデアを記録・追跡するための機能です。 チームで共有できる ToDoリストのようなもので、「何をやるべきか」「どんな問題があるか」を一か所で管理できます。
Issues とは何か
Issues は GitHub リポジトリに組み込まれたチケット管理システムです。1 つの Issue が 1 つのタスクや問題に対応します。
たとえば次のような用途で使います。
- 「ログインボタンが押せない」というバグを報告する
- 「検索機能を追加したい」という新機能の要望を記録する
- 「〇〇の実装方法を調べる」という作業タスクを作る
- 「このアーキテクチャで良いか？」というチームへの質問を投げる
なぜ Issues を使うのか
Issues を使う最大の理由は、作業の抜け漏れをなくし、チーム全員が同じ情報を見られるようにするためです。
メールやチャットでのやり取りは流れてしまいますが、Issues に記録すれば検索して見つけられます。また、誰が担当しているか・どのリリースで対応するかを明示できます。
Issue の作成方法
リポジトリの「Issues」タブを開き、「New issue」ボタンをクリックします。
| フィールド | 説明 | 記入例 |
|---|---|---|
| Title（タイトル） | 問題や作業を端的に表す | ログインボタンが特定のブラウザで動かない |
| Description（説明） | 詳細な情報・再現手順・期待する動作 | 後述のテンプレート参照 |
| Labels（ラベル） | Issue の種別を分類するタグ | bug, enhancement など |
| Assignees（担当者） | この Issue を担当する人 | @yamada |
| Milestone（マイルストーン） | リリースバージョンや期限に紐づける | v1.2.0 |
| Projects | 紐づけるプロジェクトボード | Sprint 3 |
タイトルの書き方
良いタイトルは「何が問題か・何をするか」が一読して分かるものです。
| 評価 | タイトル例 | 理由 |
|---|---|---|
| 良い | iOS Safari でログインフォームが送信できない | OS・ブラウザ・症状が明確 |
| 良い | ユーザー検索機能を追加する | 作業内容が明確 |
| 悪い | バグ | 何のバグか分からない |
| 悪い | 修正 | 何を修正するか分からない |
ラベルの使い方
ラベルは Issue を色分けして分類するタグです。一覧を見たとき、どんな Issue があるか一目で把握できます。
GitHub デフォルトのラベル
| ラベル | 意味 |
|---|---|
bug | バグ・不具合の報告 |
enhancement | 新機能・改善の提案 |
documentation | ドキュメントの修正・追加 |
good first issue | 初心者でも取り組みやすい Issue |
help wanted | 他の人の協力を求めている |
question | 質問・議論 |
wontfix | 対応しないと判断した Issue |
duplicate | 同じ内容の Issue が既に存在する |
invalid | 不正な報告や確認できない問題 |
カスタムラベルの作成
チームの運用に合わせてカスタムラベルを作れます。よく使われるカスタムラベルの例を示します。
| カスタムラベル | 意味 |
|---|---|
priority: high | 優先度高 |
priority: low | 優先度低 |
area: frontend | フロントエンド関連 |
area: backend | バックエンド関連 |
status: blocked | 他の Issue 待ちでブロック中 |
type: refactor | リファクタリング |
「Issues」タブ → 「Labels」→「New label」から作成できます。
マイルストーンの使い方
マイルストーン（Milestone）とは、特定のリリースや期限に向けて Issue をグループ化する機能です。
たとえば v1.0.0 リリース というマイルストーンを作り、そのバージョンで対応する Issue をすべてまとめると、進捗がパーセンテージで表示されます。
マイルストーンの作成手順
- 「Issues」タブ → 「Milestones」をクリック
- 「New milestone」をクリック
- タイトル（例:
v1.0.0）、期限日、説明を入力 - 「Create milestone」をクリック
Issue を閉じる方法
Issue は次の 2 つの方法で閉じられます。
手動でクローズ
Issue ページの下部にある「Close issue」ボタンをクリックします。
PR マージ時に自動クローズ
PR のタイトルや説明文に次のキーワードと Issue 番号を書くと、PR がマージされた瞬間に自動的に Issue が閉じられます。
Closes #123
Fixes #456
Resolves #789たとえば PR の説明に Closes #42 と書いておくと、その PR がマージされた瞬間に Issue #42 が自動クローズされます。作業完了と Issue クローズを手動で二重管理する手間が省けます。
Issue テンプレートの作成方法
バグ報告や機能要望の Issue を一定の形式に統一したい場合、テンプレートを作成できます。テンプレートを使うと、報告者が必要な情報を漏れなく記入できます。
バグ報告テンプレートの例
.github/ISSUE_TEMPLATE/bug_report.md を作成します。
---
name: バグ報告
about: バグを報告するためのテンプレートです
labels: bug
---
## 発生している問題
<!-- 何が起きているか簡潔に説明してください -->
## 再現手順
1. 〇〇のページを開く
2. 〇〇ボタンをクリックする
3. エラーが発生する
## 期待する動作
<!-- 本来はどうなるべきか -->
## 実際の動作
<!-- 実際には何が起きているか -->
## 環境
- OS: macOS 14.x / Windows 11 / Ubuntu 22.04
- ブラウザ: Chrome 120 / Firefox 121 / Safari 17
- アプリのバージョン: v1.2.3
## スクリーンショット
<!-- 画像があれば貼り付けてください -->機能要望テンプレートの例
.github/ISSUE_TEMPLATE/feature_request.md を作成します。
---
name: 機能要望
about: 新機能や改善を提案するためのテンプレートです
labels: enhancement
---
## 提案する機能
<!-- どんな機能を追加・改善したいか説明してください -->
## 解決したい課題
<!-- この機能がないことで困っていることを説明してください -->
## 提案する解決策
<!-- どう実装・実現するか、アイデアがあれば書いてください -->
## 代替案
<!-- 他の方法で解決できる場合は記載してください -->実際のユースケース - 実務でどう使うか
ユースケース1: バグ報告と修正の追跡
- QA チームがバグを発見 →
bugラベルを付けて Issue を作成 - 担当エンジニアをアサイン（Assignees に追加）
- エンジニアが修正ブランチを作り、PR 説明に
Fixes #42を記入 - PR がマージされると Issue #42 が自動クローズ
- QA チームがリグレッションテストを実施して確認
ユースケース2: スプリントのタスク管理
- スプリント開始時に
Sprint 5マイルストーンを作成 - このスプリントで対応する Issue をマイルストーンに紐づける
- Projects のカンバンボードで進捗を可視化（GitHub Projects）
- スプリント終了時にマイルストーンのクローズ率を確認
ユースケース3: OSS プロジェクトへのコントリビューション
good first issueラベルの Issue を探す- コメントで「対応します」と宣言する
- フォークしてブランチを作り、修正する
- PR を送り、
Closes #<Issue番号>を記載する
よくある質問
Q. Issue は誰でも作れますか？
パブリックリポジトリでは GitHub アカウントを持っていれば誰でも Issue を作れます。プライベートリポジトリはリポジトリへのアクセス権が必要です。
Q. Issue の説明にどこまで書けばよいですか？
バグ報告の場合は「再現手順・期待する動作・実際の動作・環境情報」の4つが最低限必要です。スクリーンショットや動画があればより分かりやすくなります。
Q. Issue をたくさん作りすぎて管理できなくなってきました。
ラベルとマイルストーンを活用して整理することをおすすめします。また、定期的に古い Issue を棚卸しし、対応しないものは wontfix ラベルを付けてクローズするのが有効です。
Q. Closes #123 を書いたのに Issue が閉じませんでした。
PR が main（またはデフォルトブランチ）にマージされたときのみ自動クローズが発火します。別のブランチへのマージでは発火しません。また、キーワードのスペルミス（Close ではなく Closes）や Issue 番号の誤りがないか確認してください。
Q. 同じ内容の Issue が重複して作られたときはどうすればよいですか？
どちらか一方に duplicate ラベルを付け、「〇〇は Issue #XX と重複しています」とコメントを残してクローズします。元の Issue へのリンクを貼ると後から見た人に分かりやすくなります。
このページの外部仕様・背景情報は、参考文献を参照してください。[1][2]
参考文献
- Git, Reference
- GitHub, GitHub Docs