GitHub Issues
GitHub Issuesは単なるバグトラッカーではありません。適切に活用すれば、チーム全体の開発フローを根本から改善できる強力なツールです。本記事では、GitHub Issuesの全機能を網羅的に解説し、実務で即座に活用できる知識を提供します。
1. GitHub Issuesとは
GitHub Issuesは、アイデア、フィードバック、タスク、バグなどあらゆる作業を追跡できる柔軟なシステムです。作成が迅速で、用途に応じた使い分けが可能です。以下のような用途に対応しています：
- バグ報告の管理
- 新機能のアイデア収集
- リリース追跡
- 大規模な取り組みの進捗管理
Projectsとの統合により、チーム全体の作業計画と追跡が一元化されます。
2. Issueの作成方法
2.1 基本的な作成フロー
リポジトリから直接作成する標準的な方法です：
- リポジトリのメインページで「Issues」タブをクリック
- 「New issue」をクリック
- タイトルと説明を入力
- 必要に応じてメタデータを追加（後述）
- 「Submit new issue」をクリック
2.2 多様な作成方法
実際の開発フローに合わせて、複数の作成方法が用意されています。
2.2.1 コメントからの作成
IssueやPull Requestのコメントから直接新しいIssueを作成できます。元のコメントへのリンクが自動的に含まれるため、文脈を失いません。
2.2.2 コードからの作成
特定のコード行またはコード範囲を選択してIssueを作成できます。選択したコードスニペットが自動的にIssue本文に含まれます。
2.2.3 ディスカッションからの作成
GitHub Discussionsの投稿をIssueに変換できます。ディスカッションの内容とラベルが保持され、元のディスカッションも残ります。
2.2.4 GitHub CLIでの作成
コマンドラインから直接作成することで、コンテキストスイッチを削減できます：
gh issue create --title "新しい機能の実装" --body "詳細な説明" \
--assignee @me,tanaka --label "enhancement,priority-high" \
--project "開発スプリント" --milestone "v2.0"
2.2.5 URLクエリパラメータでの作成
事前に情報が入力されたIssue作成URLを生成できます：
https://github.com/org/repo/issues/new?title=バグ報告&body=問題の説明&labels=bug&assignees=yamada
2.2.6 Copilot Chatでの作成
自然言語のプロンプトやスクリーンショットから、Copilotがタイトル、本文、ラベル、担当者などを自動入力します。リポジトリのテンプレートや構造を理解した上で、適切なIssueを生成します。
3. Sub-issuesによる階層的なタスク管理
Sub-issuesは、大規模な作業を実行可能な小タスクに分解するための機能です。最大の特徴は、親子関係が可視化され、進捗が自動的に追跡される点です。
3.1 Sub-issuesの特徴
- 階層の深さ：最大8階層まで作成可能
- 数の制限：親Issue1つにつき最大100個のSub-issue
- 進捗の可視化：親IssueにSub-issuesの完了状況が表示される
- Projects統合：Projects内でも階層構造と進捗が利用可能
3.2 Sub-issuesの作成方法
3.2.1 新規作成
- 親Issueの説明の下部にある「Create sub-issue」をクリック
- タイトルと説明を入力
- Issue type、担当者、ラベル、Projects、マイルストーンを設定
- 「Create more sub-issues」を選択すると連続作成が可能
- 「Create」をクリック
3.2.2 既存Issueの追加
- 親Issueの「Create sub-issue」横の「...」をクリック
- 「Add existing issue」を選択
- 提案から選択するか、検索フィールドでIssueを検索
- 他のリポジトリからも追加可能
3.3 Sub-issuesのナビゲーション
親Issueから展開アイコン（▶）をクリックすることで、すべての階層を閲覧できます。Sub-issueからは、ヘッダー部分に親Issueへのリンクが常に表示されます。
3.4 実践例：機能開発の分解
このような構造により、大規模な機能開発を明確なタスクに分解し、チーム全体で進捗を共有できます。
4. Issue Dependenciesによるブロック管理
Issue Dependenciesは、作業間の依存関係を明示的に定義する機能です。ボトルネックの早期発見と、作業の優先順位付けに役立ちます。
4.1 依存関係の設定
- Issueの右サイドバーで「Relationships」をクリック
- ドロップダウンから選択：
- 「Mark as blocked by」：このIssueが他のIssueに依存
- 「Mark as blocking」：このIssueが他のIssueをブロック
- 対象のIssueを検索して選択
ブロックされているIssueには、プロジェクトボードやIssue一覧で「Blocked」アイコンが表示され、依存関係が一目で分かります。
4.2 実務での活用例
この依存関係を明示することで、チームメンバーは作業の順序と優先度を正確に把握できます。
5. メタデータによる情報整理
Issueには多様なメタデータを付与することで、検索性と管理性が向上します。
5.1 Issue Types
組織レベルで最大25種類のIssue typeを定義できます。デフォルトでは以下が用意されています：
- Task：通常のタスク
- Bug：バグ報告
- Feature：新機能の要望
組織の設定で、カスタムタイプの追加、名前・説明・色の変更、無効化、削除が可能です。
5.2 ラベル
Issueを柔軟にカテゴライズするための仕組みです。デフォルトラベルの使用または独自ラベルの作成が可能です。
論理演算を使った高度なフィルタリング：
- OR検索：
label:"bug","wip"（bugまたはwipのラベル） - AND検索：
label:"bug" label:"wip"（両方のラベル）
5.3 マイルストーン
日付ベースの目標に対してIssueをグループ化します。期限が近づくにつれて進捗状況が表示されます。
5.4 担当者（Assignees）
最大10人まで担当者を設定可能です。以下の条件を満たすユーザーを割り当てられます：
- Issue/Pull Requestにコメントしたユーザー
- リポジトリへの書き込み権限を持つユーザー
- リポジトリへの読み取り権限を持つ組織メンバー
6. Projects統合による計画と追跡
ProjectsはIssuesと強力に統合されており、チーム全体の作業を視覚的に管理できます。
6.1 Projectsの特徴
- カスタマイズ可能なビュー：テーブル、ボード、ロードマップなど
- 自動同期：IssueとPull Requestの情報が自動的に反映
- 柔軟なフィルタリング：メタデータを使った詳細なフィルタ作成
- グルーピング：任意のフィールドでグループ化
6.2 Projectからの直接Issue作成
Projectのビューから直接Issueを作成すると、そのビューのグループ値が自動的に設定されます。例えば、「Status」フィールドで「Todo」グループにIssueを作成すると、StatusがTodoに自動設定されます。
7. フィルタリングと検索
大量のIssueから必要な情報を素早く見つけるための機能が充実しています。
7.1 デフォルトフィルタ
- すべてのオープンなIssueとPull Request
- 自分が作成したもの
- 自分に割り当てられたもの
- 自分がメンションされたもの
7.2 高度なフィルタ構築
7.2.1 ブール演算子
AND演算子（両方の条件が真）：
label:"question" AND assignee:tanaka
OR演算子（いずれかの条件が真）：
assignee:tanaka OR assignee:suzuki
スペースは暗黙的にAND演算子として扱われます。
7.2.2 括弧によるネスト
最大5階層まで括弧を使ってフィルタをネストできます：
(type:"Bug" AND assignee:tanaka) OR (type:"Feature" AND assignee:suzuki)
7.3 検索クエリの例
7.3.1 Issue固有の検索
# 特定のユーザーが作成
state:open is:issue author:tanaka
# 特定のユーザーが関与（@メンション以外も含む）
state:open is:issue involves:yamada
# Pull Requestにリンクされている
linked:pr
# クローズ理由で検索
is:closed reason:completed
is:closed reason:"not planned"
# 特定のタイプ
is:open type:"Bug"
# メタデータの有無
has:label
no:project
# 組織またはユーザーのリポジトリから
state:open is:issue org:myorg OR user:tanaka
7.3.2 Pull Request固有の検索
# ドラフトPR
is:draft
# レビューステータス
state:open is:pr review:none
state:open is:pr review:required
state:open is:pr review:approved
state:open is:pr review:changes_requested
# レビュアーで検索
state:open is:pr reviewed-by:suzuki
state:open is:pr review-requested:yamada
state:open is:pr user-review-requested:@me
state:open is:pr team-review-requested:myteam
# Issueにリンク
linked:issue
# マージ状態
is:merged
is:unmerged
7.4 ソート機能
以下の基準でソート可能です：
- 最新/最古の作成日時
- 最多/最少のコメント数
- 最新/最古の更新日時
- リアクション数（最多）
7.5 保存ビュー
頻繁に使用するフィルタは保存ビューとして保存できます（最大25個）。
作成方法：
- ページ上部の「Issues」アイコンをクリック
- 左サイドバーの「Views」横の「+」をクリック
- タイトル、説明、カスタムアイコンを追加
- 「Query」で高度なフィルタを構築
- 「Save view」をクリック
Tip：Pull Requestも含めるにはis:prフィルタを追加します。
7.6 フィルタの共有
フィルタやソートを適用すると、ブラウザのURLが自動的に更新されます。このURLを共有することで、チームメンバーと同じビューを共有できます。
例：
/issues?q=state:open+is:issue+assignee:suzuki+sort:created-asc
8. Pull Requestとの連携
8.1 キーワードによる自動リンク
Pull Requestの説明またはコミットメッセージで特定のキーワードを使用すると、Issueが自動的にリンクされ、Pull Requestがマージされると該当Issueがクローズされます。
8.1.1 サポートされているキーワード
以下のキーワードが使用可能です（大文字でも可、コロン付きでも可）：
- close, closes, closed
- fix, fixes, fixed
- resolve, resolves, resolved
8.1.2 構文
| 対象 | 構文 | 例 |
|---|---|---|
| 同じリポジトリ | KEYWORD #ISSUE番号 |
Closes #10 |
| 別のリポジトリ | KEYWORD オーナー/リポジトリ#ISSUE番号 |
Fixes myorg/myrepo#100 |
| 複数のIssue | 各Issueに完全な構文を使用 | Resolves #10, resolves #123, resolves myorg/myrepo#100 |
注意：キーワードはデフォルトブランチへのPull Requestでのみ解釈されます。他のブランチへのPull Requestでは無視されます。
8.2 サイドバーからの手動リンク
書き込み権限を持つユーザーは、Pull Requestのサイドバーから手動でIssueをリンクできます（最大10個）：
- Pull Requestページで右サイドバーの「Development」をクリック
- リンクするIssueをクリック
8.3 IssueサイドバーからPull Request/ブランチをリンク
Issueのサイドバーから、Pull Requestまたはブランチをリンクできます：
- Issueページで右サイドバーの「Development」をクリック
- リポジトリを選択
- Pull Requestまたはブランチを選択
- 「Apply」をクリック
9. ブランチ作成とワークフロー
Issue画面から直接作業用のブランチを作成できます（パブリックプレビュー機能）。
9.1 ブランチ作成手順
- Issueページの右サイドバーで「Development」セクションを確認
- 「Create a branch」をクリック（既にリンクがある場合は「...」→「Create a branch」）
- ブランチ名を入力（オプション）
- リポジトリを選択（オプション）
- ローカルで作業するかGitHub Desktopで開くかを選択
- 「Create branch」をクリック
デフォルトでは、現在のリポジトリのデフォルトブランチから新しいブランチが作成されます。
10. タスクリストの活用
Issueの本文内でタスクリストを使用すると、追加機能が有効になります：
- Issue上部にタスク完了数が表示される
- タスクリスト内でリンクされたIssueがクローズされると、チェックボックスが自動的にマークされる
タスクをIssueに変換する場合は、タスクにカーソルを合わせて右上のアイコンをクリックします。
11. テンプレートとフォーム
11.1 Issue Templates
リポジトリに複数のIssueテンプレートを設定できます。一般的な用途：
- リリース追跡：リリースの進捗や起動日の手順を追跡
- 大規模な取り組み：大きなプロジェクトの進捗を追跡（小さなIssueにリンク）
- 機能リクエスト：製品やプロジェクトの改善要望
- バグ報告：バグの報告
11.2 Issue Forms
標準化された情報を収集するためのフォームを作成できます。YAMLで定義します：
name: "Project Octocat のバグ報告"
description: "バグを報告するためのフォーム"
title: "[Bug]: "
labels: ["bug"]
body:
- type: markdown
attributes:
value: |
バグ報告ありがとうございます！
- type: input
id: contact
attributes:
label: "連絡先メールアドレス"
description: "問題について連絡する必要がある場合、どのように連絡すればよいですか？"
placeholder: "email@example.com"
validations:
required: false
- type: textarea
id: what-happened
attributes:
label: "何が起こりましたか？"
description: "バグについて教えてください。"
placeholder: "バグの説明..."
validations:
required: true
12. コミュニティ管理機能
12.1 READMEとCONTRIBUTING
- README.md：プロジェクトの紹介、開始方法、連絡先
- CONTRIBUTING.md：貢献のガイドライン、Issueのオープン方法
これらのファイルにより、有意義なIssueの作成を促進できます。
12.2 スラッシュコマンド（パブリックプレビュー）
複雑なMarkdownの入力を簡略化します：
| コマンド | 説明 |
|---|---|
/code |
Markdownコードブロックを挿入（言語選択可能） |
/details |
折りたたみ可能な詳細エリアを挿入 |
/saved-replies |
保存された返信を挿入 |
/table |
Markdownテーブルを挿入（行列数を選択） |
/template |
リポジトリのテンプレートを表示 |
12.3 通知とサブスクリプション
- Issueをサブスクライブすることで、最新のコメントの通知を受け取れます
- ダッシュボードで、サブスクライブしている最近更新されたIssueへのリンクを素早く確認できます
12.4 重複のマーク
類似したIssueを追跡するために、Issueを重複としてマークできます：
- コメント本文に「Duplicate of #番号」と入力
- または、GitHubの保存された返信「Duplicate issue」を使用
タイムラインの「Undo」をクリックして、重複マークを解除できます。
13. 管理機能
13.1 ピン留め
最大3つの重要なIssueをIssue一覧の上部にピン留めできます。右サイドバーの「Pin issue」をクリックします。
13.2 Issue転送
より適切なリポジトリにIssueを移動できます（同じユーザーまたは組織アカウント所有のリポジトリ間のみ）：
- Issueページで右サイドバーの「Transfer issue」をクリック
- リポジトリを選択
- 「Transfer issue」をクリック
コメントと担当者は保持され、一致する名前のラベルとマイルストーンも保持されます。元のURLは新しいIssueにリダイレクトされます。
注意：プライベートリポジトリのIssueはパブリックリポジトリに転送できません。
13.3 Issue複製
類似したIssueを素早く作成するために、既存のIssueを複製できます：
- Issueページで右サイドバーの「Duplicate issue」をクリック
- リポジトリを選択（同じまたは異なるリポジトリ）
- 事前入力された詳細を必要に応じて編集
- 「Create issue」をクリック
元のIssueのタイトル、説明、担当者、タイプ、ラベル、マイルストーン、プロジェクトが事前入力されます。
13.4 Issueのクローズ
Issueをクローズする際、理由を選択できます：
- Completed：作業が完了した
- Not planned：作業を行わない予定
検索クエリで理由を指定できます：
is:closed reason:completed
is:closed reason:"not planned"
13.5 Issueの削除
組織所有のリポジトリでは、管理者または所有者権限を持つユーザーのみが削除可能です。個人アカウント所有のリポジトリでは、そのアカウントのみが削除できます。
削除されたIssueのURLにアクセスすると、ページが見つからない旨のメッセージが表示されます。
14. AIによるIssue理解とトリアージ
14.1 GitHub Copilotによる理解支援
複雑なIssueや不慣れなIssueに取り組む際、Copilotが迅速に文脈を理解する手助けをします：
- Issueページで右上の検索バー横のアイコンをクリック
- Copilotチャットパネルで質問を入力：
- 「このIssueの主要なポイントをまとめて」
- 「このIssueの目標は何ですか？」
- 「最近のコメントを要約して」
- 「次のステップの提案は？」
14.2 AI駆動のIssueトリアージツール
GitHubアクションとして利用可能な自動トリアージツールです：
- GitHub Marketplaceで「AI assessment comment labeler」を検索
- リポジトリにインストール
- デフォルト設定では、
request ai reviewラベルを適用すると解析が開始されます - AIが分析結果をコメントまたはラベルとして追加
このツールは、大量の新しいIssueを効率的にトリアージし、実行可能かどうか、追加情報が必要かを判断します。
15. GitHub CLIの活用
15.1 Issue一覧の取得
# 基本的な一覧表示
gh issue list
# フィルタを適用
gh issue list --label bug --state open --assignee tanaka
# 詳細な出力
gh issue list --json number,title,state,assignees
15.2 Pull Request一覧の取得
# 基本的な一覧表示
gh pr list
# レビューステータスでフィルタ
gh pr list --state open --search "review:required"
# 特定のブランチのPR
gh pr list --head feature-branch
16. 実践的なワークフロー例
16.1 スプリント計画のワークフロー
バグ報告からリリースまでのフロー
17. まとめ
GitHub Issuesは、以下の機能により包括的なプロジェクト管理を実現します：
- 柔軟な作成方法：UI、CLI、API、Copilot、URLクエリなど多様な手段
- 階層的な管理：Sub-issuesによる最大8階層の作業分解
- 依存関係の可視化：Issue Dependenciesによるブロック関係の明示
- 豊富なメタデータ：Issue types、ラベル、マイルストーン、担当者
- 強力な検索：ブール演算子、ネスト、保存ビューによる効率的なフィルタリング
- Projects統合：カスタマイズ可能なビューでチーム全体の作業を視覚化
- 自動化：Pull Requestとの自動リンク、AIによるトリアージ
- コミュニティサポート：テンプレート、フォーム、スラッシュコマンド
これらの機能を適切に組み合わせることで、チームの生産性を大幅に向上させることができます。まずは基本的なIssue作成から始め、徐々にSub-issuesやProjects統合などの高度な機能を取り入れていくことをお勧めします。
実際のプロジェクトで試しながら、チームに最適なワークフローを確立してください。