GitHub - Issues
概要
GitHub Issuesは、プロジェクト内のバグ報告、機能リクエスト、タスク管理を一元化するための追跡ツールである。
Issueを活用することによりで、開発チームは作業内容を可視化し、優先度の管理や進捗追跡を効率的に行うことができる。
Issuesが提供する主な機能は以下の通りである。
- バグ報告
- 再現手順や期待動作を記録し、開発者が問題を特定・修正しやすくする。
- 機能リクエスト
- 新機能の提案や改善要望をチームで議論・評価する場として活用できる。
- タスク管理
- 開発作業をチケット形式で管理し、担当者・期日・進捗を一元管理する。
- ドキュメント・質問
- 仕様の確認や技術的な疑問点を記録し、チーム内の知識を蓄積する。
Issueはラベル、マイルストーン、アサイニーと組み合わせることにより、大規模プロジェクトの管理にも対応できる。
Issueの作成
Web UIでの作成
GitHubのWebインターフェースからIssueを作成する手順を以下に示す。
- リポジトリの[Issues]タブを選択する。
- [New issue]ボタンを押下する。
- テンプレートが設定されている場合は一覧から選択して、テンプレートなしで作成する場合は[Open a blank issue]を選択する。
- タイトルと説明 (本文) を入力する。
- 右側バーからラベル、マイルストーン、アサイニーを必要に応じて設定する。
- [Submit new issue]ボタンを選択して、Issueを作成する。
本文はMarkdown記法で記述でき、コードブロック、画像、リンクの挿入が可能である。
GitHub CLIでの作成
GitHub CLIを使用すると、コマンドの実行によりIssueを作成できる。
基本的な作成コマンドを以下に示す。
gh issue create --title "<タイトル>" --body "<説明>"
オプションを指定した例を以下に示す。
gh issue create \ --title "バグ: ログイン時にエラーが発生する" \ --body "再現手順: ..." \ --assignee @me \ --label bug \ --milestone "v1.0"
下表に、主なオプションを示す。
| オプション | 説明 |
|---|---|
--title |
Issueのタイトルを指定する。 |
--body |
Issueの本文を指定する。 |
--assignee |
担当者を指定する。@me で自分自身を指定できる。
|
--label |
ラベルを指定する。 複数指定する場合はカンマ区切りで指定する。 |
--milestone |
マイルストーンを指定する。 |
--web |
Webブラウザを開いて、Issue作成フォームを表示する。 |
URLクエリパラメータによる事前入力
Issue 作成フォームのURLにクエリパラメータを付与することで、フォームの各フィールドを事前入力した状態で開くことができる。
パラメータ付きURLの例を以下に示す。
https://github.com/owner/repo/issues/new?title=バグ報告&labels=bug,enhancement&assignees=username
下表に、利用可能なクエリパラメータを示す。
| パラメータ | 説明 | 例 |
|---|---|---|
title |
Issueタイトルを事前入力する。 | ?title=バグ報告 |
body |
Issue本文を事前入力する。 | ?body=再現手順を記載 |
labels |
ラベルをカンマ区切りで指定する。 | ?labels=bug,enhancement |
assignees |
担当者のユーザ名を指定する。 | ?assignees=username |
milestone |
マイルストーン名を指定する。 | ?milestone=v1.0 |
template |
使用するテンプレートファイル名を指定する。 | ?template=bug_report.md |
このURLをドキュメントやREADMEに掲載することにより、ユーザが適切な情報を入力しやすくなる。
Issueテンプレート
Markdownテンプレート
Markdown テンプレートを使用すると、Issue作成時に定型のフォームを提供できる。
テンプレートは .github/ISSUE_TEMPLATE/ ディレクトリ内に .md ファイルとして配置する。
ディレクトリ構成例を以下に示す。
.github/ └── ISSUE_TEMPLATE/ ├── bug_report.md ├── feature_request.md └── config.yml
テンプレートファイルの記述例を以下に示す。
---
name: バグ報告
about: バグを報告するためのテンプレート
title: "[BUG] "
labels: bug
assignees: ""
---
## バグの概要
バグの内容を簡潔に記述してください。
## 再現手順
1. ...
2. ...
## 期待する動作
本来はどのように動作すべきかを記述してください。
## 実際の動作
実際にどのように動作したかを記述してください。
## スクリーンショット
(該当する場合は画像を添付してください)
## 環境
- OS:
- Webブラウザ / バージョン:
下表に、フロントマターで指定できるフィールドを示す。
| フィールド | 説明 |
|---|---|
name |
テンプレート選択画面に表示される名前 |
about |
テンプレート選択画面に表示される説明文 |
title |
Issueタイトルの初期値 |
labels |
自動的に付与するラベル |
assignees |
自動的に割り当てる担当者 |
Issueフォーム (YAML形式)
Issueフォームは、YAML形式で定義する構造化フォームである。
Markdownテンプレートよりも厳密な入力制御が可能で、必須フィールドの設定やドロップダウンの提供ができる。
フォームファイルは .github/ISSUE_TEMPLATE/ ディレクトリ内に .yml ファイルとして配置する。
記述例を以下に示す。
name: バグ報告
description: バグを報告するためのフォーム
title: "[BUG] "
labels: ["bug"]
body:
- type: markdown
attributes:
value: |
バグ報告ありがとうございます。
以下のフォームに必要事項を入力してください。
- type: input
id: title
attributes:
label: バグの概要
placeholder: バグを一行で説明してください
validations:
required: true
- type: textarea
id: steps
attributes:
label: 再現手順
description: バグを再現する手順を記載してください
placeholder: |
1. ...
2. ...
validations:
required: true
- type: dropdown
id: severity
attributes:
label: 深刻度
options:
- 低 (軽微な問題)
- 中 (機能に影響する問題)
- 高 (クリティカルな問題)
validations:
required: true
- type: checkboxes
id: checklist
attributes:
label: 確認事項
options:
- label: 同様の Issue が既に報告されていないことを確認しました
required: true
- label: 最新バージョンで問題が発生することを確認しました
下表に、利用可能なフィールドタイプを示す。
| タイプ | 説明 |
|---|---|
markdown |
入力不可の説明文を表示する。 情報提供や注意書きに使用する。 |
input |
一行のテキスト入力フィールド |
textarea |
複数行のテキスト入力フィールド |
dropdown |
プルダウンメニューから選択するフィールド |
checkboxes |
複数選択可能なチェックボックスフィールド |
validations: required: true を指定することで、そのフィールドへの入力を必須にできる。
テンプレートチューザーのカスタマイズ
.github/ISSUE_TEMPLATE/config.yml ファイルを作成することにより、テンプレート選択画面の動作をカスタマイズできる。
config.ymlファイルの記述例を以下に示す。
blank_issues_enabled: false
contact_links:
- name: セキュリティの脆弱性
url: https://example.com/security
about: セキュリティの脆弱性はこちらから報告してください
- name: コミュニティフォーラム
url: https://forum.example.com
about: 一般的な質問はフォーラムをご利用ください
下表に、config.ymlファイル設定項目を示す。
| 項目 | 説明 |
|---|---|
blank_issues_enabled |
false に設定すると、テンプレートを使用せずにIssueを作成することを禁止する。 全てのIssueにテンプレートの使用を強制する場合に設定する。 |
contact_links |
テンプレート選択画面に外部リソースへのリンクを追加する。 セキュリティポリシーページやコミュニティフォーラムへの誘導に利用できる。 |
Issueの管理
編集・クローズ・再オープン
作成済みの Issue は、権限を持つユーザが編集、クローズ、再オープンを行うことができる。
- 編集
- Issueの右上メニューから[Edit]を選択して、タイトルや本文を変更して[Update comment]を選択する。
- クローズ
- Issueページ下部の[Close issue]ボタンを押下して、クローズ時にコメントを追加することもできる。
- 再オープン
- クローズ済みのIssueで[Reopen issue]ボタンを押下する。
GitHub CLIでクローズ、再オープンを行う例を以下に示す。
# Issueをクローズする gh issue close 123 # Issueを再オープンする gh issue reopen 123
Issueの削除
Issue の削除は永続的な操作であり、削除後の復元はできない。
削除権限は以下の通りである。
- 個人所有リポジトリ
- リポジトリの所有者のみが削除できる。
- 組織所有リポジトリ
- 組織の管理者 (Admin) またはオーナー (Owner) のみが削除できる。
削除はコメントも含めてリポジトリから完全に除去される。
誤削除を防ぐため、通常はクローズ操作を推奨する。
Issueのピン留め
リポジトリのIssuesページの上部に最大3つのIssueをピン留めして目立たせることができる。
ピン留めの手順を以下に示す。
- ピン留めしたいIssueを開く。
- 右側バーの[Pin issue]を選択する。
- Issuesページの上部にIssueが固定表示される。
ピン留めを解除するには、同じ手順で[Unpin issue]を選択する。
ピン留めは最大3つまでという制限があるため、重要度の高いIssueを選んで設定する。
Issueの転送
Issueを別のリポジトリに転送することができる。
転送できる範囲は同一ユーザまたは同一組織内のリポジトリに限られる。
転送時のデータ保持ルールを以下に示す。
- 保持されるもの
- コメント、担当者の情報は転送先でも保持される。
- 条件付きで保持されるもの
- ラベルとマイルストーンは、転送先リポジトリに同名のラベル、マイルストーンが存在する場合のみ保持される。
GitHub CLIでの転送例を以下に示す。
gh issue transfer 123 new-owner/new-repo
ラベル
デフォルトラベル
新しく作成されたリポジトリには、以下に示す9つのデフォルトラベルが自動的に設定される。
| ラベル名 | 用途 |
|---|---|
bug |
予期しない動作や不具合を示す。 |
documentation |
ドキュメントの改善や追加が必要であることを示す。 |
duplicate |
既存のIssue または Pull Requestと重複していることを示す。 |
enhancement |
新機能の追加や既存機能の改善を示す。 |
good first issue |
初めてコントリビュートする人に適したIssueであることを示す。 |
help wanted |
メンテナーがコミュニティの協力を求めていることを示す。 |
invalid |
Issueの内容が正確でない または 無効であることを示す。 |
question |
質問や調査が必要なIssueであることを示す。 |
wontfix |
このIssueへの対応を行わないことを示す。 |
カスタムラベルの管理
プロジェクト固有のラベルを作成・編集・削除することができる。
ラベル管理画面へのアクセス手順を以下に示す。
- リポジトリの[Settings]を開く。
- 左メニューから[Issues]を選択する。
- [Labels]セクションで[New label]を選択する。
- ラベル名、説明、カラーを設定して、[Save label]を選択する。
カラーは16進数カラーコード (例: #d73a4a) で指定する。
[Generate a random color]ボタンでランダムな色を自動生成することもできる。
GitHub CLIでのラベル作成例を以下に示す。
gh label create "priority:high" --color "e11d48" --description "<高優先度のIssue>"
マイルストーン
マイルストーンの作成と管理
マイルストーンは、リリースや期日に向けたIssue、Pull Requestのグループ管理機能である。
マイルストーンの作成手順を以下に示す。
- [Issues]タブを開く。
- [Milestones]ボタンを押下する。
- [New milestone]を選択する。
- 名前、説明、期日を入力して、[Create milestone]を選択する。
下表に、設定できる項目を示す。
| 項目 | 説明 |
|---|---|
| 名前(必須) | マイルストーンを識別するための名前 バージョン番号 (例: v1.0.0) や スプリント名が使われることが多い。 |
| 説明 | マイルストーンの目的や含まれる作業内容の概要 |
| 期日 | マイルストーンの完了期日 設定すると期日超過時に警告が表示される。 |
進捗の追跡
マイルストーンページでは、紐付けられたIssueとPull Requestの進捗を確認できる。
表示される情報を以下に示す。
- オープン数とクローズ数
- 未完了と完了のIssue/Pull Requestの件数が表示される。
- 完了パーセンテージ
- クローズ済みのチケット数をもとに完了率が自動計算されて表示される。
- 期日までの残り日数
- 期日が設定されている場合、残り日数または超過日数が表示される。
アサイン (担当者)
担当者の割り当て
Issueに担当者を割り当てることで、誰がそのIssueを対応するかを明確にできる。
担当者の割り当て手順を以下に示す。
- Issueを開く。
- 右側バーの[Assignees]を選択する。
- ユーザ名を検索して選択する。
担当者には、リポジトリへのコラボレータとして登録されているユーザのみを指定できる。
複数担当者
1つのIssueには最大10名の担当者を割り当てることができる。
GitHub CLIでの一括割り当て例を以下に示す。
gh issue edit 123 --add-assignee "user1,user2,user3"
担当者を外す場合は以下のコマンドを使用する。
gh issue edit 123 --remove-assignee "user1"
Sub-issues
Sub-issueとは
Sub-issuesは、Issueを階層構造で管理するための機能である。
2025年1月13日に正式提供が開始された。
Sub-issuesを使用することにより、大きなタスクを細かな作業単位に分割して、進捗を階層的に管理できる。
複数リポジトリにまたがるSub-issuesの作成もサポートされている。
Sub-issueの作成と管理
下表に、Sub-issuesの仕様を示す。
| 項目 | 説明 |
|---|---|
| 最大数 | 1つのIssueに対して最大100個のSub-issuesを作成できる。 |
| ネスト階層 | 最大8段階のネストが可能である。 |
| クロスリポジトリ | 同一組織内の別リポジトリのIssueをSub-issueとして登録できる。 |
Sub-issueの作成手順を以下に示す。
- 親となるIssueを開く。
- Issueページ内の[Create sub-issue]ボタンを押下する。
- 新規作成 または 既存Issueの追加を選択する。
- 必要な情報を入力して作成する。
進捗の可視化
Sub-issuesを設定すると、親IssueのページでSub-issuesの完了状況がプログレスバーで表示される。
下表に、表示される情報を示す。
| 項目 | 説明 |
|---|---|
| 完了数と総数 | 完了したSub-issues数と全体のSub-issues数が表示される。 |
| 完了率バー | クローズ済みのSub-issuesの割合がビジュアルで表示される。 |
従来のタスクリスト (チェックボックス) よりも柔軟な管理が可能であり、Sub-issuesへの移行が推奨される。
検索とフィルタリング
フィルタ構文
Issuesの検索バーでは、フィルタ構文を使用して絞り込み検索ができる。
下表に、主なフィルタ構文を示す。
| 構文 | 説明 |
|---|---|
is:open |
オープン状態のIssueを表示する。 |
is:closed |
クローズ済みのIssueを表示する。 |
assignee:@me |
自分が担当者のIssueを表示する。 |
assignee:username |
指定ユーザが担当者のIssueを表示する。 |
label:"bug" |
指定ラベルが付いたIssueを表示する。 |
milestone:"v1.0" |
指定マイルストーンに紐付いたIssueを表示する。 |
author:username |
指定ユーザが作成したIssueを表示する。 |
created:2025-01-01..2025-12-31 |
指定期間内に作成されたIssueを表示する。 |
sort:created-desc |
作成日時の降順で並べ替える。 |
no:assignee |
担当者が未設定のIssueを表示する。 |
no:label |
ラベルが未設定のIssueを表示する。 |
AND / OR演算子を組み合わせることで複合条件の検索が可能である。
ネストは最大5段階まで対応している。
よく使用される検索クエリ
開発でよく使用される検索クエリの例を以下に示す。
| クエリ | 用途 |
|---|---|
| is:open assignee:@me | 自分が担当するオープン中のIssueを確認する。 |
| is:open label:bug | バグラベルの付いたオープン中のIssueを確認する。 |
| is:open no:assignee label:bug | 担当者未設定のバグIssueを確認する。 |
| is:open milestone:"v2.0" | 次のリリースに向けたオープンIssueを確認する。 |
| is:closed author:@me | 自分が作成したクローズ済みIssueを確認する。 |
| is:open label:"good first issue" | 初心者向けのオープンIssueを確認する。 |
| is:open sort:created-asc | 長期間オープンのまま放置されたIssueを確認する。 |
タスクリスト
タスクリストの記法
Issueの本文にMarkdownのチェックボックス記法を使用してタスクリストを作成できる。
記法例を以下に示す。
## 対応チェックリスト
- [x] 問題の調査
- [x] 修正方針の確定
- [ ] コードの修正
- [ ] テストの実施
- [ ] ドキュメントの更新
記法のルールを以下に示す。
- [ ]- 未完了のタスクを表す。
- [x]- 完了済みのタスクを表す。
チェックボックスは、Issueページ上でクリックして切り替えることができる。
タスクの完了数は、Issue一覧ページでもインジケーターとして表示される。
Sub-issuesへの移行
従来のタスクリストブロック機能は廃止され、Sub-issuesの使用が推奨されている。
Sub-issuesへの移行を推奨する理由を以下に示す。
- 独立したトラッキング
- 各タスクが独立したIssueとして管理されるため、個別のラベル・担当者・マイルストーン設定が可能になる。
- 進捗の可視化
- 親Issueのページでプログレスバーによる完了率の可視化ができる。
- クロスリポジトリ対応
- 異なるリポジトリのIssueをSub-issueとして紐付けることができる。
- 検索・フィルタリング
- Sub-issuesを個別に検索・フィルタリングできる。
IssueとPull Requestの連携
キーワードによる自動クローズ
Pull Request (PR) の説明文 または コミットメッセージに特定のキーワードとIssue番号を記述することにより、PRのマージ時に関連するIssueを自動的にクローズできる。
下表に、自動クローズキーワードを示す。
| キーワード | バリエーション |
|---|---|
| close | close / closes / closed |
| fix | fix / fixes / fixed |
| resolve | resolve / resolves / resolved |
使用例を以下に示す。
## 変更内容
ログインエラーの原因を修正しました。
Closes #123
## 関連 Issue
Fixes octo-org/octo-repo#100
自動クローズが機能する条件を以下に示す。
- デフォルトブランチ (通常は main または master) をターゲットにしたPRでのみ有効である。
- 同一リポジトリのIssueは、Closes #123 の形式で指定する。
- 別リポジトリのIssueは、Closes octo-org/octo-repo#100 の形式で指定する。
クロスリファレンス
IssueやPRの本文・コメントに #番号 を記述することにより、リポジトリ内の他のIssueやPRへの自動リンクが生成される。
クロスリファレンスの使用例を以下に示す。
この問題は #123 に関連しています。
また、#456 で報告された問題と同じ原因である可能性があります。
クロスリファレンスの仕様を以下に示す。
- 同一リポジトリ参照
#番号でIssueまたはPRへのリンクが自動生成される。
- 別リポジトリ参照
owner/repo#番号の形式で別リポジトリのIssueやPRを参照できる。
- PRからIssueへのリンク
- PRの右側バーの[Development]セクションに、関連するIssueが表示される。
- リンク上限
- 1つのPRに紐付けられるIssueは最大10件までである。
