GitHub Issueとは
GitHub Issueは、バグ、改善、作業、アイデアなどをリポジトリ単位で記録し、追跡するための仕組みです。
単なるメモとして使うこともできますが、学習や個人開発では「これから何をするのか」「なぜするのか」「どこまでできれば完了なのか」を作業開始前に固定する単位として使うと効果的です。
たとえば「READMEを直す」だけでは、何を直せば終了なのか曖昧です。Issueに目的と完了条件を書いてから作業を始めれば、変更の範囲を決めやすくなります。
Issueの基本構造
最小構成では、titleとbodyを意識します。
title
一覧を見ただけで作業内容が分かる短い題名にします。
曖昧な例：
README修正
より良い例：
READMEにセットアップ手順を追加する
後者なら、何を変更するIssueなのかをタイトルだけで判断できます。
body
bodyには最低限、次の3点を書いておくと作業票として使いやすくなります。
- 目的・背景
- 実施する内容
- 完了条件
例：
## 目的
初めてリポジトリを開いた人が実行方法を理解できるようにする。
## 作業内容
- READMEに必要環境を追記する
- インストール手順を追記する
- 実行コマンドを追記する
## 完了条件
- READMEだけを読んでセットアップから実行まで再現できる
- 記載したコマンドを実際に確認する
完了条件を書く理由
Issueで特に重要なのが完了条件です。
「READMEを改善する」では終了判定が人によって変わります。一方、「READMEだけを読んでセットアップから実行まで再現できる」と書けば、作業後に確認できます。
つまりIssueは、作業内容の記録だけでなく、作業開始前に終了条件を決める場所として使えます。
良いIssueと曖昧なIssue
曖昧なIssue：
Title: エラーを直す
動かないので修正する。
この書き方では、どの操作で何が起きるのか、期待する結果は何か、何を確認すれば完了なのか分かりません。
改善例：
Title: 空の入力で発生するエラーを処理する
## 現象
入力欄を空のまま実行するとエラーになる。
## 期待する動作
空入力の場合は処理を開始せず、入力を促すメッセージを表示する。
## 完了条件
- 空入力で例外終了しない
- メッセージが表示される
- 正常な入力では従来どおり処理できる
後者なら、Issueを見て作業を開始でき、終了時にも同じIssueを使って確認できます。
Issueからbranchへつなぐ
Issueを作ったら、その作業専用のbranchを作ると変更の目的とコードを分離しやすくなります。
例としてIssue #12に対応するなら、branch名を次のようにできます。
issue-12-readme-setup
GitHubにはIssueからbranchを作成・接続する機能もあります。ただし、このUIや機能は変更される可能性があります。GitHub公式ドキュメントでは、IssueのDevelopment領域からbranchを作成する機能はpublic previewとして案内されています。
ローカルでbranchを作る場合は、通常のGit操作でも構いません。
git switch -c issue-12-readme-setup
大切なのはbranch名そのものではなく、「このbranchはどのIssueのための変更か」を追跡できる状態にすることです。
commitからIssueを参照する
GitHub上の会話では、#12のようなIssue番号への参照がリンクとして扱われます。
commit messageでも、変更内容がIssueに対応していることが分かる書き方にしておくと履歴を追いやすくなります。
例：
Add setup instructions to README (#12)
ただし、Issue番号を書いただけで常にIssueが自動closeされると考えないようにします。自動closeにはPull Requestとのリンクやclosing keywordなど、GitHub側の規則があります。
Pull RequestからIssueへつなぐ
作業が終わったらbranchをpushし、Pull Requestを作成します。
Pull Requestの説明に次のように書くと、対応するIssueとの関係を明確にできます。
Closes #12
GitHub公式ドキュメントでは、close、fix、resolve系のclosing keywordをIssue参照と組み合わせてPull Requestへ記述できます。条件を満たして既定branchへmergeされると、リンクされたIssueを自動的にcloseできます。
したがって、基本的な流れは次のようになります。
Issue
↓
branch
↓
commit
↓
push
↓
Pull Request
↓
merge
↓
Issue close
Issueは開発フローの入口として使えます。
個人開発でもIssueを使う意味
Issueはチーム専用の機能ではありません。個人開発でも有効です。
コードを書き始める前にIssueを作れば、思いつきと実際の作業を分離できます。また、後から「なぜこの変更をしたのか」を調べるときにも、commitだけより背景を残しやすくなります。
小さな個人開発なら、すべてを細かくIssue化する必要はありません。30分以上かかる変更、完了条件を決めたい変更、後で理由を振り返りたい変更などから使い始めると運用しやすくなります。
Issueで使える補助情報
GitHub Issueにはlabels、milestones、assigneesなどのメタデータを追加できます。GitHub公式ドキュメントではIssue typeや依存関係などの機能も提供されています。
ただし、最初からすべてを使う必要はありません。まずはtitle、body、完了条件、Issue→branch→PRの接続を理解し、必要になった段階で分類機能を追加する方が運用を複雑にしにくくなります。
GitHubの画面は変わる可能性がある
GitHubのWeb UI、ボタン名、配置、Issue関連機能は更新される可能性があります。そのため、この記事では特定の画面配置を暗記するのではなく、Issueが「作業の目的・背景・完了条件を保存し、実装と結び付ける単位」であることを中心に扱います。
画面が記事と異なる場合は、GitHub公式ドキュメントの最新手順を確認してください。
まとめ
GitHub Issueは、単なる「やることメモ」ではなく、開発作業を始める前に目的と完了条件を固定し、その後のbranch・commit・Pull Requestへ接続できる作業管理単位です。
最初は次の流れだけで十分です。
1. Issueを作る
2. 目的と完了条件を書く
3. Issueに対応するbranchで作業する
4. commit・pushする
5. Pull RequestからIssueを参照する
6. merge後にIssueが完了したことを確認する
この流れを身につけると、GitHub上に「何を変えたか」だけでなく「なぜ変えたか」「何をもって完了としたか」まで残せるようになります。
