GitHub Issueは単なるバグ報告ツールではありません。ラベル・テンプレート・Sub-issues・Projectsを組み合わせることで、チーム開発のタスク管理基盤として機能します。

ただし、機能を知っているだけでは運用は回りません。「どのルールで」「どう設計して」「どう定着させるか」が成否を分けます。

この記事では、GitHub Issueの基本機能の解説にとどまらず、チームで実際に回せる運用ルールの設計方法まで踏み込みます。2024年以降に追加されたSub-issues・Issue Types・Iteration Fieldなどの新機能も含めて、実務で使える形で整理しています。

GitHub Issueの役割と他ツールとの違い

GitHub Issueは、リポジトリに紐づくチケットシステムです。バグ報告・機能要望・タスク管理・ドキュメント改善要求など、開発プロジェクトで発生する「やるべきこと」を一元管理する場所として使います。

JiraやTrelloなどの外部タスク管理ツールとの最大の違いは、コードと同じ場所にあることです。コミットメッセージに #42 と書けばIssue #42へのリンクが自動生成され、PRに Closes #42 と書けばマージ時にIssueが自動クローズされます。コードの変更履歴とタスクの対応関係を追跡するために別ツール間を行き来する必要がありません。

Issue・Pull Request・Discussionsの使い分け

GitHub上にはIssue以外にもPull RequestやDiscussionsがあり、混同しやすいため整理します。

機能目的状態管理コードとの連携
Issueやるべき作業の定義と追跡Open / Closedコミット・PRから参照・自動クローズ
Pull Requestコード変更のレビューとマージOpen / Merged / ClosedIssueと紐付けて自動クローズ
Discussionsオープンな議論・質問・提案Open / Answeredなし（Issueへ変換可能）

運用のコツとして、判断が確定していない段階のアイデアや質問はDiscussionsに投稿し、実行することが決まった段階でIssueに変換するという流れが効果的です。Discussionsの画面から「Convert to Issue」ボタンで即座にIssueへ変換できます。

Issue作成の実践 タイトルと本文の書き方

効果的なIssueを書くための具体的な方法を整理します。

タイトルの原則

タイトルは一覧表示で見たときに内容が推測できる粒度で書きます。以下の比較を参考にしてください。

分類良くない例改善例
バグ「ログイン画面のバグ」「ログイン画面でメールアドレスに+記号を含むとバリデーションエラーになる」
機能追加「検索機能の改善」「商品検索にカテゴリフィルターを追加する」
リファクタリング「コードの修正」「UserServiceのN+1クエリを解消する」

「何が」「どうなっているか（あるべき姿との差分）」 をタイトルに含めると、一覧を眺めるだけで優先順位の判断ができます。

本文のテンプレート構造

バグ報告の場合は次の4項目を必ず含めます。

## 現象
ログイン画面でメールアドレスに `+` 記号（例: user+test@example.com）を
入力して送信すると、「無効なメールアドレスです」とエラー表示される。

## 期待される動作
RFC 5321に準拠したメールアドレスはバリデーションを通過し、
ログイン処理が実行される。

## 再現手順
1. /login にアクセス
2. メールアドレス欄に `user+test@example.com` を入力
3. パスワードを入力して「ログイン」ボタンをクリック

## 環境
- ブラウザ: Chrome 132.0
- OS: macOS 15.3
- デプロイ環境: staging

機能追加の場合は、受け入れ条件（Acceptance Criteria）をチェックリスト形式で記述すると、完了の定義が明確になります。

## 概要
商品検索にカテゴリフィルターを追加し、ユーザーが目的の商品に
素早くたどり着けるようにする。

## 受け入れ条件
- [ ] 検索画面にカテゴリドロップダウンが表示される
- [ ] 全カテゴリ（10件）が選択肢に含まれる
- [ ] カテゴリ選択後、検索結果が即時フィルタリングされる
- [ ] カテゴリ未選択時は全商品が表示される
- [ ] モバイル画面（幅375px以下）で正常に動作する

この受け入れ条件をチェックリストで書く方法は、海外のアジャイル開発チームで広く採用されています。「このIssueが完了したかどうか」を担当者以外のメンバーも客観的に判断できるため、レビューやQAの手戻りが減ります。

ラベル設計 チームで統一する命名規則

ラベルはIssueを分類するための色付きタグです。GitHubにはデフォルトで bug enhancement documentation などが用意されていますが、チームの運用に合わせてカスタマイズするのが一般的です。

プレフィックスによる体系化

ラベルが増えると一覧が混沌とします。海外の大規模OSSプロジェクトで広く使われているのが、プレフィックス（接頭辞）による名前空間の分離です。

プレフィックス用途ラベル例カラー例
type:Issueの種類type: bug type: feature type: docs赤系
priority:優先度priority: critical priority: low橙〜黄系
status:進捗ステータスstatus: in-progress status: blocked青系
scope:対象領域scope: frontend scope: api scope: infra緑系

この方式にはメリットが2つあります。

  1. フィルタリングが容易になる: label:type:bug label:priority:critical のように検索クエリを組み合わせて、緊急対応が必要なバグだけを絞り込める
  2. ラベル選択時に迷わない: 新しいメンバーでも type: から1つ、priority: から1つ選ぶというルールに従えば、必要なラベルを付け漏らさない

カラーの統一ルール

同じプレフィックスのラベルには同系色を割り当てると、Issue一覧を眺めたときに視覚的にカテゴリを識別できます。GitHubのラベル管理画面（Settings > Labels）からカラーコードを16進数で設定します。

運用上の注意点

ラベルの数は20個以内に抑えるのが実務上のバランスです。選択肢が多すぎると付与が面倒になり、結果として「ラベルを付けない文化」が定着してしまいます。定期的に使用頻度の低いラベルを棚卸しして統廃合するサイクルを設けてください。

Issue テンプレートとconfig.ymlによる運用の強制

テンプレートを設定すると、Issue作成時に定型フォーマットが自動挿入されます。

Markdownテンプレートの設置

リポジトリの .github/ISSUE_TEMPLATE/ ディレクトリにMarkdownファイルを配置します。

<!-- .github/ISSUE_TEMPLATE/bug_report.md -->
---
name: バグ報告
about: 動作の不具合やエラーの報告
title: "[Bug] "
labels: "type: bug"
assignees: ""
---

## 現象
<!-- 何が起きているかを具体的に記述してください -->

## 期待される動作
<!-- 本来どう動くべきかを記述してください -->

## 再現手順
1.
2.
3.

## 環境
- ブラウザ:
- OS:
- デプロイ環境:

config.ymlでテンプレート選択を強制する

デフォルトでは、テンプレートを設置しても「空のIssue」を作成するオプションが残ります。チームの運用品質を保つには、自由記述のIssue作成を禁止し、テンプレートの選択を強制する設定が有効です。

# .github/ISSUE_TEMPLATE/config.yml
blank_issues_enabled: false
contact_links:
  - name: セキュリティに関する報告
    url: https://example.com/security
    about: 脆弱性の報告はこちらから（非公開で対応します）
  - name: 質問・相談
    url: https://github.com/yourorg/yourrepo/discussions
    about: 使い方の質問や提案はDiscussionsへお願いします

blank_issues_enabled: false を設定すると、テンプレートなしのIssue作成ができなくなります。contact_links には外部URLやDiscussionsへの誘導リンクを追加でき、質問とバグ報告の混在を防げます。

脆弱性報告の分離

セキュリティ上の脆弱性を公開Issueで報告されると、修正が完了する前に攻撃者に情報が渡るリスクがあります。GitHubには Security Advisories（セキュリティアドバイザリー） という非公開の報告チャネルが用意されています。

リポジトリの Settings > Code security and analysis（Securityセクション内）> Private vulnerability reporting を有効化すると、報告者はIssueではなく非公開フォームから脆弱性を報告できます。上記の config.yml と組み合わせて、Issueテンプレート選択画面からセキュリティ報告専用の導線を設けておくと安全です。

Sub-issuesとDependenciesで大きな作業を分解する

GitHubが2025年4月にGA（一般提供）した機能として、Sub-issues（子Issue） と Issue Dependencies（依存関係） があります。

Sub-issuesの使い方

従来はIssue本文にチェックリスト（- [ ] 小タスク）を書いて擬似的にタスク分解していましたが、Sub-issuesを使うと各小タスクが独立したIssueとして管理できます。

  • 親Issueの画面で「Add sub-issue」から子Issueを作成または既存Issueをリンク
  • 子Issueにはそれぞれ担当者・ラベル・マイルストーンを個別設定可能
  • 親Issueの画面に子Issueの進捗バーが自動表示される
  • 複数階層のネスト（親 → 子 → 孫）も対応

大きな機能開発（例: 「決済機能のリニューアル」）をSub-issuesで分解すると、全体の見通しと個別タスクの進捗を同時に追跡できます。

Dependenciesで作業の順序を明示する

Issue Dependencies機能では、Issue間の「ブロック / ブロックされる」関係を設定できます。

例: 「API設計の確定（#50）」が完了しないと「フロントエンド実装（#51）」に着手できない場合、#51に「Blocked by #50」を設定します。Projects のボードビューでは、ブロック状態のIssueにアイコンが表示されるため、進捗のボトルネックが可視化されます。

Issue Typesでリポジトリ横断の分類を統一する

Issue Types はラベルとは別の軸でIssueを分類する機能です。Organization（組織）レベルで定義するため、複数リポジトリにまたがって一貫した分類が適用されます。

ラベルとの違いは次のとおりです。

比較項目ラベルIssue Types
定義の範囲リポジトリごとOrganization全体
複数選択可不可（1つのみ）
主な用途細かな属性付与Issueの本質的な種別定義
Projectsとの連携フィルタに使用可グループ化・フィルタに使用可

Organization の Settings > Issue types から Bug Feature Task Incident などの種別を定義しておくと、組織内のどのリポジトリでIssueを作成しても同じ種別が選択できます。Projectsのグループ化やフィルタでもIssue Typeを軸にできるため、組織横断のバグ集計や機能要望の俯瞰に便利です。

ブランチ・コミット・PRとIssueを連携させる

GitHub Issueの価値は、コードの変更履歴と結びつくことで最大化されます。

IssueからブランチをUIで作成する

Issueの右サイドバーにある「Development」セクションの「Create a branch」から、そのIssueに紐づいたブランチを作成できます。

ブランチ名は自動で 42-fix-login-validation のようにIssue番号とタイトルから生成されます。ソースブランチ（mainやdevelopなど）も選択可能です。CLIで作成する場合は、以下のような命名規則を統一しておくと管理しやすくなります。

# 命名規則: {type}/{issue番号}-{概要}
git checkout -b fix/42-login-validation
git checkout -b feature/55-category-filter
git checkout -b docs/60-api-reference

コミットメッセージでIssueを参照する

コミットメッセージに #42 のようにIssue番号を含めると、GitHub上でコミットとIssueが自動的にリンクされます。

git commit -m "メールアドレスのバリデーション正規表現を修正 #42"

この参照はIssueのタイムラインにも表示されるため、後からIssueを見たときに「どのコミットで対応したか」を追跡できます。

PRでIssueを自動クローズする

PRの本文に以下のキーワードとIssue番号を含めると、PRがマージされた時点でIssueが自動クローズされます。

  • Closes #42（close closed も同様）
  • Fixes #42（fix fixed も同様）
  • Resolves #42（resolve resolved も同様）

1つのPRで複数のIssueをクローズすることも可能です。

Closes #42, Closes #43

注意点として、PRがデフォルトブランチ（mainやmaster）にマージされた場合のみ自動クローズが発動します。developブランチへのマージでは自動クローズされないため、ブランチ戦略と合わせて運用設計が必要です。

GitHub Projectsとの連携でタスク全体を管理する

GitHub ProjectsはIssueとPRをボード・テーブル・ロードマップ形式で可視化するプロジェクト管理ツールです。複数リポジトリのIssueを1つのProjectに集約できるため、マイクロサービス構成やモノレポでも統合的にタスクを管理できます。

ボードビューのカラム設計

Kanban方式のボードビューで管理する場合、以下のカラム構成が実用的です。

カラム役割WIP上限の目安
Backlog着手可能だが未着手のIssue上限なし
In Progress現在作業中のIssueチーム人数 x 1〜2
In ReviewPRが出されてレビュー待ち上限なし
Doneマージ済み・クローズ済み自動アーカイブ推奨

Projects v2ではカラムにアイテム数の上限を設定できます。これはアジャイル開発のWIP（Work In Progress）制限に相当し、チームが同時に抱える作業量をコントロールする仕組みです。In Progressのカラム上限をチーム人数に合わせて設定することで、一人が複数タスクを抱えてマルチタスクになる状況を防ぎます。

Iteration Fieldでスプリントを管理する

Projects v2の Iteration Field（イテレーションフィールド） を使うと、Issueを1〜2週間のスプリント単位で管理できます。

  • カスタムフィールドとして Iteration を追加
  • スプリントの期間（1週間・2週間など）を設定
  • 各IssueをIterationに割り当て
  • スプリント単位でフィルタリング・集計が可能
  • 休暇・祝日期間の除外設定にも対応

JiraやLinearなどの有料ツールに頼らなくても、GitHub内でスプリントベースの開発サイクルを回せます。

Roadmapビューでスケジュールを俯瞰する

Projects v2のRoadmapレイアウトはガントチャート形式の表示です。Issueに開始日と終了日を設定すると、タイムライン上に横棒で表示されます。

Assignee（担当者）でグループ化すると、チームメンバーごとの作業負荷の偏りが一目でわかります。「GitHub タスク管理 ガントチャート」で検索している方が求めている機能はこのRoadmapビューです。

Insightsでプロジェクトの健全性を測る

Projects v2には Insights（インサイト） 機能が組み込まれており、カスタムチャートでプロジェクトの進捗を可視化できます。

  • バーンアップチャート: 期間内のIssueクローズ推移
  • ステータス別の内訳グラフ
  • 担当者別・ラベル別のフィルタリング

チームのレトロスペクティブ（振り返り）やステークホルダーへの進捗報告資料として、GitHub外のツールを使わずにデータを取得できます。

GitHub Actionsで運用を自動化する

手動の運用ルールはメンバーが増えると形骸化しやすいため、可能な限り自動化します。

ラベルの自動付与

ファイルパスに応じてラベルを自動付与するGitHub Actionsの設定例です。

# .github/labeler.yml
frontend:
  - changed-files:
    - any-glob-to-any-file: 'src/frontend/**'

backend:
  - changed-files:
    - any-glob-to-any-file: 'src/api/**'

docs:
  - changed-files:
    - any-glob-to-any-file: 'docs/**'

# .github/workflows/labeler.yml
name: Labeler
on:
  pull_request_target:
    types: [opened, synchronize]
permissions:
  contents: read
  pull-requests: write
jobs:
  label:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/labeler@v6

放置Issueの自動クローズ

長期間更新のないIssueが溜まると、バックログが膨張して優先度判断が困難になります。actions/stale を使って、一定期間アクティビティのないIssueに警告ラベルを付与し、さらに放置された場合にクローズする自動化が有効です。

# .github/workflows/stale.yml
name: Close stale issues
on:
  schedule:
    - cron: '0 0 * * 1'  # 毎週月曜日に実行
jobs:
  stale:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/stale@v10
        with:
          stale-issue-message: |
            このIssueは60日間更新がないため、staleラベルを付与しました。
            7日以内にコメントがない場合、自動クローズされます。
          days-before-stale: 60
          days-before-close: 7
          stale-issue-label: 'status: stale'

Projectsへの自動追加

新規Issueを作成するたびに手動でProjectsに追加するのは手間です。GitHub Actionsで自動化できます。

# .github/workflows/add-to-project.yml
name: Add to project
on:
  issues:
    types: [opened]
jobs:
  add:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/add-to-project@v1
        with:
          project-url: https://github.com/orgs/yourorg/projects/1
          github-token: ${{ secrets.PROJECT_TOKEN }}

CONTRIBUTING.mdで運用ルールを明文化する

チームの運用ルールは口頭やSlackで共有するだけでは定着しません。リポジトリのルートに CONTRIBUTING.md を配置すると、Issue作成画面にこのファイルへのリンクが自動表示されます。

CONTRIBUTING.mdに含めるべき内容の例です。

# コントリビューションガイド

## Issue作成の前に
1. 既存のIssue一覧を検索して、同じ報告がないか確認してください
2. 重複を見つけた場合は、既存Issueに 👍 リアクションを付けてください
3. 新規Issueはテンプレートに従って作成してください

## ブランチの命名規則
- `fix/{issue番号}-{概要}` バグ修正
- `feature/{issue番号}-{概要}` 新機能
- `docs/{issue番号}-{概要}` ドキュメント

## コミットメッセージ
- 本文にIssue番号を含めてください（例: `修正内容 #42`）
- PRの説明に `Closes #42` を含めてください

## セキュリティ脆弱性の報告
セキュリティに関わる問題はIssueではなく、
Security Advisoryから非公開で報告してください。

「Issue作成前に検索する」というルールをCONTRIBUTING.mdに明記する方式は、大規模OSSプロジェクトで標準的に採用されています。重複Issueの削減効果が高く、GitHub自身のリポジトリでもこのパターンが使われています。

チームへの定着 運用を形骸化させないコツ

ルールを整備しても、チームに定着しなければ意味がありません。

最初は最小構成で始める

いきなり完璧なラベル体系やテンプレートを揃えようとすると、メンバーの学習コストが高くなり、「面倒だからIssueを書かない」という状況に陥ります。

最初のステップとして推奨する最小構成は次のとおりです。

  1. ラベル: type: bug type: feature type: docs の3種類だけ
  2. テンプレート: バグ報告テンプレート1つだけ
  3. ルール: PRには必ず Closes #番号 を含める

2〜4週間運用して、メンバーがIssue作成に慣れてきたら priority: ラベルやマイルストーンを追加します。

放置Issueの定期棚卸し

月に1回、30分のバックログ棚卸しの時間を設けます。

  • 3か月以上更新のないIssueを一覧化する
  • 「まだ必要か」「優先度は変わっていないか」をチームで確認
  • 不要になったIssueはクローズし、クローズ理由をコメントに残す

前述の actions/stale による自動化と組み合わせると、棚卸しの対象が絞られて効率的です。

Excelやスプレッドシートからの移行

現在ExcelやGoogleスプレッドシートでタスク管理をしているチームは、次の手順で段階的に移行できます。

  1. まずIssueを「起票の場所」にする: スプレッドシートの新規行追加をやめ、GitHub Issueで起票する
  2. Projectsのテーブルビューで既存のスプレッドシートを再現する: カスタムフィールドを追加すれば、スプレッドシートと同じカラム構成をProjects上で実現できる
  3. スプレッドシートを参照専用にする: 2〜4週間の並行運用期間を経て、新規更新をGitHub側に一本化する

Projects v2のテーブルビューはスプレッドシートに近いUIのため、非エンジニアのメンバーにとっても違和感が少ない形で移行できます。

GitHub Issueのバックアップ

Issueのデータはリポジトリのコード（Gitオブジェクト）とは独立して管理されています。つまり、git clone ではIssueのデータは取得されません。Issue本文・コメント・ラベル・マイルストーン・担当者情報などのメタデータは、GitHub APIを通じてのみ取得可能です。

重要なプロジェクトでは、GitHub REST APIを使ったバックアップスクリプトや、GitProtect・Rewind（旧BackHub）などのSaaS型バックアップサービスの導入を検討してください。GitHub自体の障害やアカウントの問題でデータにアクセスできなくなるリスクへの備えです。

まとめ

GitHub Issueの運用を成功させるポイントは、機能の理解と運用ルールの設計の両方を押さえることです。

基本として押さえる機能:

  • タイトルと本文の書き方（受け入れ条件のチェックリスト）
  • ラベルのプレフィックス命名と20個以内の運用
  • テンプレートと config.yml によるIssue品質の強制
  • ブランチ・コミット・PRとの連携（自動クローズ）

チーム開発で活用すべき機能:

  • Sub-issuesで大きなタスクを階層分解
  • Issue TypesでOrganization横断の分類を統一
  • ProjectsのIterationフィールドでスプリント管理
  • Roadmapビューでスケジュールと負荷を可視化
  • GitHub Actionsでラベル付与・放置Issue対策・Projects追加を自動化

運用を定着させるコツ:

  • 最小構成（ラベル3種 + テンプレート1つ + PRルール1つ）から始める
  • CONTRIBUTING.mdにルールを明文化し、Issue作成画面から自然に誘導する
  • 月1回の棚卸しで不要Issueを整理する

GitHub Issueは無料プランでもほぼすべての機能が利用できます。外部ツールを導入する前に、まずGitHub内の機能を使い切ることで、コードとタスクの一元管理という最大の利点を活かせます。