GitHub Issueとは？使い方・書き方と運用のベストプラクティス【2026年版】

GitHub Issueは、GitHubのリポジトリに付属する課題管理機能です。バグ報告・機能要望・作業タスクを「#123」のような番号付きのチケットとして起票し、議論から修正のPull Requestまでを1か所でつなぎます。なお、Git本体にIssueの機能はありません。「git issue」で調べている場合も、GitHubやGitLabといったホスティングサービス側の機能を指しています。

この記事では、Issueの作り方と伝わる書き方に加え、2025〜2026年に増えたIssue types・sub-issues・Issue fieldsの使い分けと、Pull Requestをマージしても自動でクローズされない原因までを扱います。仕様は2026年9月時点のGitHub Docsと、GitHub CLI 2.101.0（2026年9月15日リリース）を基準にしています。

まとめ：GitHub Issueの要点

• Issueはリポジトリ単位の番号付きチケット。作業やバグはIssue、コード変更はPull Request、結論を決めない相談はDiscussionsに置く。
• タイトルは「事象＋場所＋条件」、本文は「再現手順・期待する結果・実際の結果・環境」。必須項目を守らせるならYAMLのIssueフォームが確実。
• 横断タグはラベル（新規リポジトリに既定10個）、種類はIssue types（既定はTask・Bug・Feature）、優先度や期限はIssue fields（2026年7月2日GA）。Issue typesとIssue fieldsはOrganizationのリポジトリだけで使える。
• 大きな作業はsub-issues（親1件に最大100件・8階層）と、blocked by／blockingの依存関係で分解する。
• PR本文の Closes #10 でIssueが閉じるのは、デフォルトブランチへのマージ時だけ。develop 宛てのPRではキーワードが無視される。
• 運用で効くのは「1 Issue＝独立して完了できる作業単位」と、クローズ理由（完了・対応しない・重複）の使い分け。

GitHub Issueの役割とPull Request・Discussionsとの違い

Issue（イシュー）は英語で「課題・問題」という意味です。1件のIssueには、タイトル、本文、コメントのスレッド、担当者、ラベル、マイルストーン、紐づくProjectsやPull Requestがまとまります。「誰が・何を・どこまで終えたか」の記録がリポジトリのそばに残るため、コミットやPRから経緯をたどれる点がスプレッドシートや外部のタスク管理ツールとの違いです。

迷いやすいのが、Pull RequestとDiscussionsとの使い分けです。GitHub Docsの計画と追跡のガイドは、Issueをバグや性能の報告・四半期計画・新しい施策の設計といった具体的な議論に使い、Discussionsを「コードベースの外やリポジトリをまたいだ、結論を決めないブレインストーミングやフィードバック」に使うよう案内しています。

判断の目安は「完了条件を書けるか」です。書けるならIssue、書けないうちはDiscussionsで話し、結論が出たところでIssueに起こします。Discussionのサイドバーにある「Create issue from discussion」を使うと、本文とラベルを引き継いだIssueを作れます（triage以上の権限が必要）。

Issueの作り方：Web画面とGitHub CLI

Web画面からは次の順で作成します。

1. リポジトリの Issues タブを開き、New issue をクリックする。
2. テンプレートが用意されていれば種類を選ぶ。無ければそのまま入力画面に進む。
3. タイトルと本文を書く。入力中に似た既存Issueが候補として表示されることがあるので、重複していないか確認する。
4. 権限に応じて設定できる担当者（Assignees）、ラベル、Type、Projects、マイルストーンを指定し、Submit new issue で登録する。

Issuesタブが見当たらない場合は、リポジトリの Settings にある「Features」でIssuesが無効になっています。同じ場所で、起票できる人を「Collaborators only」に絞る設定もできます。

コードの特定行について起票したいときは、ファイル表示で行番号を選び「Reference in new issue」を使うと、該当コードの抜粋付きでIssueが作られます。

ターミナルからは GitHub CLI の gh issue create を使います。2026年6月10日リリースの v2.94.0 で --type（Issue type）、--parent（sub-issueとして追加）、--blocked-by／--blocking（依存関係）が加わりました。以下は gh auth login で認証を済ませ、対象リポジトリのローカルディレクトリで実行する例です。最初の例では、本文を事前に bug.md へ保存しておきます。

# バグ報告を起票し、自分を担当者にする
gh issue create --title "Safari 18でログインフォームの送信ボタンが反応しない" \
  --body-file bug.md --label bug --type Bug --assignee "@me"

# 親Issue #120 のsub-issueとして作る
gh issue create --title "パスワード再設定メールの文面を差し替える" --parent 120

# #200 と #201 が片付くまで着手できないタスクとして作る
gh issue create --title "決済APIをv2へ切り替える" --blocked-by 200,201

--project でProjectsに追加するには、CLIの認証に project スコープが必要です（gh auth refresh -s project）。--type は後述のIssue typesを使っているOrganizationのリポジトリでだけ意味を持ちます。

伝わるIssueの書き方：タイトルと本文の型

Issueタイトル：事象・場所・条件の明示

「バグ」「ログインできない」のようなタイトルは、一覧で他のIssueと区別しにくく、検索結果から目的のIssueを絞り込みにくくなります。何が起きたか、どの画面や機能で、どんな条件のときかを1行に収めます。

• 悪い例：「ログインできない」
• 良い例：「Safari 18でログインフォームの送信ボタンが反応しない」
• タスクの例：「CSVエクスポートに注文日の列を追加する」

タスクのタイトルは「〜を検討」「〜の改善」ではなく、終わった状態が分かる動詞で書きます。「改善」は閉じる基準が無く、半年後も開いたまま残りがちです。

本文：再現手順・期待する結果・実際の結果・環境

バグ報告は、読んだ人がそのまま再現できるかで価値が決まります。本文はMarkdownで書けるので、見出しとチェックリストで型を固定すると抜けが減ります。

## 再現手順
1. https://example.com/login を Safari 18.6 で開く
2. メールアドレスとパスワードを入力する
3. 「ログイン」ボタンを押す

## 期待する結果
ダッシュボードに遷移する

## 実際の結果
ボタンが無反応。コンソールに次のエラーが出る
```
TypeError: undefined is not an object (evaluating 'form.requestSubmit')
```

## 環境
- macOS 15.6 / Safari 18.6
- 本番環境、2026-09-25 のデプロイ以降

## 関連
- #98（フォームのバリデーション変更）
- [ ] 再現を確認した

GitHubのMarkdownでは、#98 と書くと同じリポジトリのIssueやPRへ自動でリンクされます。@ユーザー名 で相手に通知が飛び、- [ ] はクリックで切り替えられるチェックボックスになります。スクリーンショットは本文へのドラッグ＆ドロップで添付できます。

機能要望とタスク：背景と完了条件の記載

要望やタスクでは、実装方法より先に「なぜ必要か」と「何ができたら閉じるか」を書きます。たとえばGitHub Issueで「CSVエクスポートに注文日の列を追加する」と依頼するなら、背景は「経理担当者が注文日別に集計するため」、完了条件は「出力したCSVに注文日がYYYY-MM-DD形式で含まれる」と具体化します。完了条件が箇条書きで並んでいれば、レビューする人もPRと突き合わせて確認できます。実装方法まで起票時に決め打ちすると、議論の余地を狭めます。

Issueフォーム：.github/ISSUE_TEMPLATEの配置と必須入力の設定

毎回同じ項目を書いてもらうなら、テンプレートを置きます。以下のテンプレートとconfig.ymlは、リポジトリのデフォルトブランチにコミットまたはマージすると、新規Issueの作成画面に反映されます。テンプレートにはMarkdown形式とYAML形式（Issueフォーム）の2種類があり、どちらもリポジトリの .github/ISSUE_TEMPLATE に置きます。Markdown形式は本文の下書きを差し込むだけで、記入者が消せば項目ごと無くなります。Issueフォームは入力欄として描画され、required: true の項目を空のまま送信できません。

Issueフォームの必須キーは name・description・body の3つです。任意で labels・assignees・type・projects を指定すると、起票時に自動で付きます。入力欄の種類は markdown（説明文）、textarea、input、dropdown、checkboxes、upload です。

# .github/ISSUE_TEMPLATE/bug_report.yml
name: バグ報告
description: 期待どおりに動かない箇所を報告する
type: Bug
labels: ["triage"]
body:
  - type: textarea
    id: steps
    attributes:
      label: 再現手順
      placeholder: "1. ... 2. ... 3. ..."
    validations:
      required: true
  - type: textarea
    id: expected
    attributes:
      label: 期待する結果と実際の結果
    validations:
      required: true
  - type: dropdown
    id: env
    attributes:
      label: 発生環境
      options:
        - 本番
        - ステージング
        - ローカル
    validations:
      required: true

注意点が2つあります。labels に書いたラベルがリポジトリに存在しないと、そのラベルは付きません。projects は起票者がそのProjectへの書き込み権限を持っている必要があり、外部からの起票を集めるならProjects側の自動追加ワークフローを使います。

同じフォルダに config.yml を置くと、テンプレートを使わない白紙のIssueを抑止し、質問や脆弱性報告を別の窓口へ誘導できます。以下のOWNERとREPOは実際の所有者名とリポジトリ名に置き換え、Discussionsを有効にしてください。脆弱性報告のリンクは、公開リポジトリでPrivate vulnerability reportingを有効にした場合に使用し、それ以外では実際に受け付けている非公開窓口のURLに置き換えます。

# .github/ISSUE_TEMPLATE/config.yml
blank_issues_enabled: false
contact_links:
  - name: 使い方の質問
    url: https://github.com/OWNER/REPO/discussions
    about: 質問はDiscussionsへお願いします
  - name: 脆弱性の報告
    url: https://github.com/OWNER/REPO/security/advisories/new
    about: 公開のIssueには書かないでください

blank_issues_enabled: false でも、Write・Maintain・Admin権限を持つ人には「Maintainers only」付きの白紙Issueの選択肢が残ります。白紙を選べなくなるのはRead・Triage権限の人です。

ラベル・Issue types・Issue fieldsの使い分け

Issueを分類する仕組みは4つあります。2025年以降にIssue typesとIssue fieldsが加わり、ラベル1つで種類も優先度も状態も表す運用は不要になりました。

ラベル：既定の10個と設計の失敗パターン

新しいリポジトリには accessibility・bug・documentation・duplicate・enhancement・good first issue・help wanted・invalid・question・wontfix の10個が最初から入っています。good first issue を付けたIssueは、リポジトリの contribute ページに一覧表示されます。Organizationのオーナーは、配下の新規リポジトリに入る既定ラベルを差し替えられます。

よくある失敗は、bug と type: bug、priority: high と P1 のように同じ意味のラベルが増えることです。Organizationで運用しているなら、種類はIssue types、優先度はIssue fieldsへ移し、ラベルは「frontend」「api」のような担当領域と、「needs-triage」のような状態に絞ると重複しません。

Issue types：Organization共通の種類と追加設定

Issue typesは、1件のIssueに1つだけ付ける「種類」です。すべてのOrganizationにTask・Bug・Featureが既定で入っており、名前・説明・色を変えたり、無効化・削除したりできます。1つのOrganizationで最大25個まで作れます。

追加するには、OrganizationのオーナーがOrganizationの Settings を開き、サイドバーの「Code, planning, and automation」にある Planning から Issue types を選び、Create new type をクリックします。リポジトリ単位の設定ではないため、個人アカウントのリポジトリの設定画面には出てきません。種類で絞り込むときは type:"Bug" と検索します。

Issue fields：優先度・期限の型と既定項目

Issue fieldsは2026年7月2日に、Free・Team・Enterpriseの全Organization向けに一般提供（GA）になりました。有効にすると、次の4項目が自動で作られます。

• Priority（単一選択）：Urgent・High・Medium・Low
• Effort（単一選択）：High・Medium・Low
• Start date（日付）
• Target date（日付）

項目の種類は単一選択・複数選択・テキスト・数値・日付の5つで、Organizationあたり最大25個まで作成できます。値は field.priority:high や field."target date":>=2026-03-01 で検索でき、GitHub MCPサーバー経由でAIツールから読み書きすることもできます。

Issue typesもIssue fieldsもOrganizationの機能です。個人リポジトリで優先度や期限を持たせるなら、priority: high のようなラベルに加え、期限をマイルストーンの期日で表すか、ProjectsのDateフィールドを使います。

sub-issuesと依存関係：作業の分解と着手順序

1件で終わらない作業は、親Issueの下にsub-issueをぶら下げます。親Issueの本文の下にある Create sub-issue から新規に作るか、既存のIssueを「Add existing issue」で子にします。上限は親1件あたり100件、入れ子は8階層までです。sub-issueの進み具合はProjectsのビューにも表示されます。

順序の制約は、依存関係（Issue dependencies）で表します。「blocked by（〜が終わるまで着手できない）」と「blocking（〜の着手を止めている）」の2種類があり、それぞれ1件のIssueに最大50件までリンクできます。

分解の目安は「sub-issue 1件をPull Request 1本で閉じられるか」です。親Issueは目的と完了条件だけを持ち、実作業は子に書きます。親に作業内容を書き込むと、子との二重管理になります。

Pull RequestでIssueを閉じる：closing keywordsと閉じない原因

PRの説明文かコミットメッセージにキーワードとIssue番号を書くと、マージ時にIssueが自動でクローズされます（GitHub Docs：プルリクエストを問題にリンクする）。使えるキーワードは close・closes・closed・fix・fixes・fixed・resolve・resolves・resolved の9語で、Closes: #10 のようなコロン付きや、CLOSES #10 のような大文字でも解釈されます。

マージしたのにIssueが閉じないときは、次の順に確認します。

• PRの向き先がデフォルトブランチ以外：キーワードが解釈されるのは、デフォルトブランチ（多くは main）を対象にしたPRだけです。develop 宛てのPRでは、リンクも作られず、マージしてもIssueに影響しません。git-flowのように統合ブランチを挟む運用では、main へのリリースPRにキーワードを書き直すか、手動で閉じます。
• 2件目以降にキーワードを付けていない：Closes #10, #11 では #11 は閉じません。1件ごとにキーワードが要ります。
• キーワードをPRのコメントに書いた：解釈されるのはPRの説明文とコミットメッセージです。

コミットメッセージにキーワードを書いた場合もデフォルトブランチへのマージでIssueは閉じますが、そのPRは「リンクされたPR」としてIssueに表示されません。キーワードを使わずにつなぐなら、PRかIssueのサイドバーの Development から手動でリンクします（PR 1本につき最大10件）。

Issueから作業を始めるときは、gh issue develop がIssueにリンクされたブランチを作ります。v2.99.0（2026年9月1日）からは、今の作業ツリーを変えずに別のworktreeへ取り出せるようになりました。ブランチの切り方そのものはブランチの仕組みと使い方を参照してください。

# Issue #123 用のブランチを作ってチェックアウトする
gh issue develop 123 --checkout

# 現在の作業ツリーはそのままに、別ディレクトリのworktreeで作業する
gh issue develop 123 --checkout --worktree ../wt-issue-123

Issueの検索とフィルタ：よく使う修飾子

Issue一覧の検索欄には修飾子を組み合わせて入力します。

2025年4月からは AND・OR と括弧を使った検索ができ、括弧は5階層まで入れ子にできます。たとえば (type:"Bug" AND assignee:octocat) OR (type:"Feature" AND assignee:hubot) は、octocat担当のバグとhubot担当の機能要望をまとめて表示します。

同じ条件はCLIでも使えます。gh issue list は、指定しなければ未完了のIssueを30件まで表示します。

# 担当者未定の bug または help wanted を古い順に並べる
gh issue list --search 'no:assignee label:"help wanted",bug sort:created-asc'

# Issue typeで絞ってJSONで取り出す
gh issue list --type Bug --json number,title,labels --limit 100

GitHub Projects：進捗ビューとフィールドの設計

複数のIssueをまとめて進めるなら、Projectsに載せます。1つのProjectに複数のビューを作り、それぞれTable（表）、Board（カンバン）、Roadmap（タイムライン）のいずれかで表示できます。Projectに追加できるフィールドはText・Number・Date・Single select・Multi select・Iterationの6種類で、Single selectの「Status」列をBoardの列にするのが基本の形です。ボードの列の切り方やWIP制限の考え方はカンバン方式のタスク管理で詳しく扱っています。

Issue fieldsの値はProjectsのビューでも絞り込みや並べ替えに使えます。ただし、公開・内部公開のProjectで表示できるのは、可視性をPublicに設定したIssue fieldsだけです。Organizationで運用するなら、優先度をProject独自のフィールドで作り直すより、Issue fieldsのPriorityを使うほうがリポジトリをまたいで値が揃います。

Issue運用のベストプラクティスと失敗パターン

Issueの粒度：独立して完了できる作業単位

「管理画面を改善する」のように閉じる基準が無いIssueは、誰も完了を判断できず、開いたまま残りがちです。目的や担当が異なり、独立して完了を判定できる作業はsub-issueに分けます。同じ変更に対する複数の受け入れ条件は、1件のIssue内にまとめます。起票したらすぐ担当者と種類を決め、担当者が決まらないものは no:assignee で週1回まとめて振り分ける、といった仕分けの時間を決めておくと未整理のIssueが溜まりません。

Issueの終了処理：クローズ理由と削除の判断基準

Issueは「Close issue」の横のメニューから、完了（completed）・対応しない（not planned）・重複（duplicate）の理由を選んで閉じられます。理由を選んでおけば、後から reason:"not planned" で「見送った要望」だけを振り返れます。

完全な削除はリポジトリのadmin権限を持つ人しかできず、Organizationのリポジトリではオーナーが削除を許可している必要があります。削除してもコラボレーターには通知されず、URLを開くとページが見つからない表示になります。経緯が消えるので、スパムや誤って書いた機密情報でない限り、削除ではなくクローズを選びます。

Issueの整理：移管・ピン留め・質問窓口の分離

• 別のリポジトリで扱うべき未完了のIssueは移管できます。ただし、非公開リポジトリから公開リポジトリへの移管はできません。移管元と移管先の両方に書き込み権限が必要で、同じユーザーか同じOrganizationが所有するリポジトリ間に限られます。
• 既知の障害や貢献ガイドのように全員に見てほしいIssueは、一覧の上部に最大3件までピン留めできます。
• 質問がIssueに混ざるなら、前述の config.yml の contact_links でDiscussionsへ誘導します。

AIエージェント向けIssue：作業指示と変更範囲の明示

GitHub CLIでは gh issue create --assignee "@copilot" のように、有料のCopilotプランでIssueをCopilotに割り当てる指定ができます（GitHub Enterprise Serverは非対応）。この使い方では、Issueの本文がそのまま作業指示になります。再現手順・完了条件・触ってはいけない範囲が書かれていないIssueでは、AIエージェントが不足情報を補って実装し、意図と違うPRを作るおそれがあります。人に渡すときと同じ型で書くことが、AIに任せる場合でも品質を左右します。Issueを起点に開発を回す考え方はチケット駆動開発（TiDD）、GitHubのIssueやPRをAIから操作する仕組みはGitHub MCPサーバーで解説しています。

JiraなどほかのツールでIssue管理をしている場合は、JiraとGitHubの連携でコミットやPRをJira側の課題に結び付けられます。ブランチ戦略やコミット規約までチームで揃えるなら、Git運用のベストプラクティスもあわせて確認してください。

よくある質問

GitHubのIssueの読み方と意味は？

「イシュー」と読みます。英語で「課題・問題」という意味で、GitHubではリポジトリごとにバグ報告・機能要望・作業タスクを番号付きで管理するチケットを指します。

GitにIssueの機能はありますか？

ありません。Git本体はバージョン管理のツールで、IssueはGitHubやGitLabなどのホスティングサービスが提供する機能です。GitHubとGitLabでのIssueやCI/CDの違いはGitHubとGitLabの違いで比較しています。

GitHubのIssueは削除できますか？

削除できるのはリポジトリのadmin権限を持つ人だけです。Organizationのリポジトリでは、さらにオーナーがIssueの削除を許可している必要があります。記録を残すため、通常は削除ではなく「not planned」などの理由を付けてクローズします。

Issue typeを追加するにはどうすればよいですか？

Organizationの Settings から「Planning」の「Issue types」を開き、Create new typeで追加します。Organizationあたり最大25個まで作れます。Issue typesはOrganizationの機能なので、個人アカウントのリポジトリでは種類をラベルで表します。

GitHub Issueで優先度や期限を管理するには？

Organizationなら、Issue fieldsの既定項目PriorityとTarget dateを使います。個人リポジトリでは、優先度をラベル、期限をマイルストーンの期日かProjectsのDateフィールドで表します。

関連記事

• チケット駆動開発（TiDD）とは？No Ticket, No Commitのルールとツール設定
• Git運用のベストプラクティス｜ブランチ戦略・コミット規約・レビュー基準の決め方
• JiraとGitHubを連携する方法｜GitHub for Jiraで課題キー・スマートコミット設定
• カンバン方式のタスク管理とは？ボードの作り方とWIP制限・リードタイムの測り方
• コミットとは？Gitが変更履歴を記録する仕組みと粒度・メッセージ設計を実装視点で解説