---
title: "GitHub Issueとは？使い方・書き方と運用のベストプラクティス【2026年版】"
url: "https://www.issoh.co.jp/tech/details/5898/"
published: 2025-03-18
updated: 2026-09-26
categories: ["GitHub"]
publisher: "株式会社一創"
---

# 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の計画と追跡のガイド](https://docs.github.com/ja/issues/tracking-your-work-with-issues/learning-about-issues/planning-and-tracking-work-for-your-team-or-project)は、Issueをバグや性能の報告・四半期計画・新しい施策の設計といった具体的な議論に使い、Discussionsを「コードベースの外やリポジトリをまたいだ、結論を決めないブレインストーミングやフィードバック」に使うよう案内しています。

| 機能           | 置くもの          | 終わり方              |
| ------------ | ------------- | ----------------- |
| Issue        | バグ、要望、作業タスク   | クローズ（完了・対応しない・重複） |
| Pull Request | コード変更の提案とレビュー | マージまたはクローズ        |
| 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個                 |
| Issue types  | Organization | 1件に1つの種類      | Task・Bug・Feature／最大25 |
| Issue fields | Organization | 優先度・工数・日付などの値 | 既定4項目／最大25            |
| マイルストーン      | リポジトリ        | 期日付きのリリース単位   | なし                    |

### ラベル：既定の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）](https://github.blog/changelog/2026-07-02-issue-fields-are-now-generally-available/)になりました。有効にすると、次の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：プルリクエストを問題にリンクする](https://docs.github.com/ja/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue)）。使えるキーワードは `close`・`closes`・`closed`・`fix`・`fixes`・`fixed`・`resolve`・`resolves`・`resolved` の9語で、`Closes: #10` のようなコロン付きや、`CLOSES #10` のような大文字でも解釈されます。

| 対象            | 書き方の例                          |
| ------------- | ------------------------------ |
| 同じリポジトリのIssue | `Closes #10`                   |
| 別リポジトリのIssue  | `Fixes octo-org/octo-repo#100` |
| 複数のIssue      | `Resolves #10, resolves #123`  |

マージしたのに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へ取り出せるようになりました。ブランチの切り方そのものは[ブランチの仕組みと使い方](/tech/details/13782/)を参照してください。

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

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

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

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

| 探したいもの           | 修飾子                              |
| ---------------- | -------------------------------- |
| 未完了のIssue        | `is:issue is:open`               |
| 対応しないで閉じたIssue   | `is:closed reason:"not planned"` |
| ラベルで絞る           | `label:"bug"`                    |
| 担当者が決まっていない      | `no:assignee`                    |
| 自分が担当            | `assignee:@me`                   |
| Issue typeで絞る    | `type:"Bug"`                     |
| Issue fieldの値で絞る | `field.priority:high`            |
| ラベルが1つでも付いている    | `has:label`                      |

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制限の考え方は[カンバン方式のタスク管理](/column/details/15654/)で詳しく扱っています。

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）](/tech/details/8798/)、GitHubのIssueやPRをAIから操作する仕組みは[GitHub MCPサーバー](/tech/details/6209/)で解説しています。

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

## よくある質問

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

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

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

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

### 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のルールとツール設定](/tech/details/8798/)
- [Git運用のベストプラクティス｜ブランチ戦略・コミット規約・レビュー基準の決め方](/column/details/2379/)
- [JiraとGitHubを連携する方法｜GitHub for Jiraで課題キー・スマートコミット設定](/tech/details/3548/)
- [カンバン方式のタスク管理とは？ボードの作り方とWIP制限・リードタイムの測り方](/column/details/15654/)
- [コミットとは？Gitが変更履歴を記録する仕組みと粒度・メッセージ設計を実装視点で解説](/tech/details/13558/)

---

出典: [GitHub Issueとは？使い方・書き方と運用のベストプラクティス【2026年版】](<https://www.issoh.co.jp/tech/details/5898/>)（株式会社一創）