github-research-tool/docs/features/02-issues-management.md

🎫 GitHub Issues 管理

GitHub Issuesを活用したプロジェクト管理とタスク追跡の完全ガイド。外部のプロジェクト管理ツールを使わずに、効率的な開発プロセスを構築する方法を学習します。

🎯 学習目標

• Issuesを使った効果的なタスク管理
• ラベル・マイルストーン・プロジェクトとの連携
• テンプレートによる標準化
• 自動化による効率向上
• 外部ツール（Jira等）との比較理解

📚 目次

1. Issues基本操作
2. ラベル管理
3. マイルストーン管理
4. Issueテンプレート
5. プロジェクトとの連携
6. 自動化・効率化
7. 外部ツールとの比較

---

1. Issues基本操作

📝 Issue作成

Web UIでの作成

1. リポジトリページ → Issues → New issue
2. 入力項目：
   - Title: 簡潔で分かりやすいタイトル
   - Comment: 詳細な説明（Markdown記法使用可能）
   - Assignees: 担当者の指定
   - Labels: 分類用ラベル
   - Projects: 関連プロジェクト
   - Milestone: 対象マイルストーン

GitHub CLI での作成

# 基本的なIssue作成
gh issue create --title "バグ修正: ログイン機能が動作しない" --body "ログインボタンをクリックしても反応がない"

# テンプレートを使用してIssue作成
gh issue create --template bug_report.md

# ラベルと担当者を指定
gh issue create --title "新機能: ユーザープロフィール" --label "enhancement,frontend" --assignee username

🔍 Issue検索・フィルタリング

高度な検索クエリ

# オープンなIssuesのみ
is:open is:issue

# 自分が担当のIssues
is:issue assignee:@me

# 特定のラベルが付いたIssues
is:issue label:bug

# 複数条件の組み合わせ
is:issue is:open label:enhancement assignee:username

# 作成日でフィルタ
is:issue created:>2024-01-01

# コメント数でフィルタ
is:issue comments:>5

# マイルストーンでフィルタ
is:issue milestone:"Version 2.0"

GitHub CLI での検索

# オープンなバグIssuesを表示
gh issue list --label bug --state open

# 自分が担当のIssuesを表示
gh issue list --assignee @me

# JSONで出力（スクリプト処理用）
gh issue list --json number,title,labels,assignees

💬 Issue管理

コメントとやり取り

# メンション機能
@username こちらの件、確認をお願いします。

# 他のIssue参照
この問題は #123 と関連があります。

# コミット参照
この修正は a1b2c3d で対応済みです。

# PR参照
修正は #45 で対応中です。

Issue状態管理

# CLI でIssueをクローズ
gh issue close 123 --comment "修正が完了しました"

# 理由を指定してクローズ
gh issue close 123 --reason "completed"  # または "not planned"

# Issueを再オープン
gh issue reopen 123

# 担当者を変更
gh issue edit 123 --add-assignee newuser --remove-assignee olduser

---

2. ラベル管理

🏷️ 効果的なラベル体系

推奨ラベル構成

# 種類別（Type）
- bug: バグ報告
- enhancement: 新機能・改善
- documentation: ドキュメント関連
- question: 質問・サポート
- duplicate: 重複Issue

# 優先度別（Priority）
- priority:high: 緊急度高
- priority:medium: 通常優先度
- priority:low: 低優先度

# 状態別（Status）
- status:ready: 作業可能
- status:in-progress: 作業中
- status:blocked: ブロックされている
- status:review: レビュー待ち

# 領域別（Area）
- area:frontend: フロントエンド
- area:backend: バックエンド
- area:api: API関連
- area:ui-ux: UI/UX
- area:performance: パフォーマンス
- area:security: セキュリティ

# サイズ別（Effort）
- size:small: 小規模（1-2日）
- size:medium: 中規模（3-5日）
- size:large: 大規模（1週間以上）

ラベル作成と管理

# GitHub CLI でラベル作成
gh label create "priority:high" --color "FF0000" --description "緊急度の高いタスク"

# 既存ラベルの編集
gh label edit "bug" --color "FF6B6B" --description "バグ報告"

# ラベル一覧表示
gh label list

# ラベル削除
gh label delete "outdated-label"

🎨 ラベルの色分けとベストプラクティス

色分けの推奨方式

🔴 高優先度・緊急: #FF0000 (赤)
🟠 中優先度: #FFA500 (オレンジ)  
🟡 低優先度: #FFFF00 (黄)
🟢 完了・承認: #00FF00 (緑)
🔵 情報・質問: #0000FF (青)
🟣 進行中: #800080 (紫)
⚫ ブロック・問題: #000000 (黒)

---

3. マイルストーン管理

🎯 マイルストーンの設計

効果的なマイルストーン例

# バージョンベース
- v1.0.0 - 初回リリース (2024-03-01)
- v1.1.0 - 機能追加 (2024-04-15)
- v2.0.0 - メジャーアップデート (2024-06-30)

# 機能ベース
- User Authentication System
- Payment Integration
- Mobile App Support

# 時期ベース
- Q1 2024 Goals
- Summer Release
- Year-end Cleanup

マイルストーン作成と管理

# マイルストーン作成
gh issue create-milestone "v1.0.0" --description "初回リリース" --due-date "2024-03-01"

# マイルストーン一覧
gh issue list-milestones

# Issueをマイルストーンに割り当て
gh issue edit 123 --milestone "v1.0.0"

📊 進捗管理

マイルストーン進捗の可視化

# マイルストーンページで確認できる情報：
- 全体の進捗率（パーセンテージ）
- オープン・クローズされたIssue数
- 期限までの残り時間
- 各Issueの状態

---

4. Issueテンプレート

📄 テンプレート作成

バグ報告テンプレート

# .github/ISSUE_TEMPLATE/bug_report.yml
name: 🐛 バグ報告
description: バグを報告するためのテンプレート
title: "[BUG] "
labels: ["bug", "needs-triage"]
assignees:
  - maintainer-username
body:
  - type: markdown
    attributes:
      value: |
        バグを報告いただき、ありがとうございます。以下の情報を詳しく記入してください。

  - type: textarea
    id: bug-description
    attributes:
      label: 🐛 バグの説明
      description: バグの詳細な説明を記入してください
      placeholder: 何が起こっているか、期待される動作との違いを説明
    validations:
      required: true

  - type: textarea
    id: reproduction-steps
    attributes:
      label: 🔄 再現手順
      description: バグを再現する手順を記入してください
      placeholder: |
        1. ○○のページに移動
        2. ○○をクリック
        3. ○○を入力
        4. エラーが発生
    validations:
      required: true

  - type: textarea
    id: expected-behavior
    attributes:
      label: ✅ 期待される動作
      description: 本来はどのような動作を期待していましたか？
    validations:
      required: true

  - type: textarea
    id: environment
    attributes:
      label: 🖥️ 環境情報
      description: 環境に関する情報
      placeholder: |
        - OS: [例: Windows 10, macOS 13.0, Ubuntu 20.04]
        - ブラウザ: [例: Chrome 108, Firefox 107, Safari 16]
        - バージョン: [例: v1.2.3]
    validations:
      required: true

  - type: textarea
    id: additional-context
    attributes:
      label: 📋 追加情報
      description: スクリーンショット、ログ、その他関連情報があれば記入してください
      placeholder: エラーメッセージ、スクリーンショットなど

機能要求テンプレート

# .github/ISSUE_TEMPLATE/feature_request.yml
name: ✨ 機能要求
description: 新機能や改善の要求
title: "[FEATURE] "
labels: ["enhancement", "needs-discussion"]
body:
  - type: markdown
    attributes:
      value: |
        新機能の提案をありがとうございます！

  - type: textarea
    id: problem-description
    attributes:
      label: 🎯 解決したい問題
      description: この機能によってどのような問題を解決したいですか？
      placeholder: 現在困っていることや、改善したい点を説明してください
    validations:
      required: true

  - type: textarea
    id: proposed-solution
    attributes:
      label: 💡 提案する解決策
      description: どのような機能や改善を提案しますか？
      placeholder: 具体的な機能の説明や実装案があれば記入してください
    validations:
      required: true

  - type: textarea
    id: alternatives
    attributes:
      label: 🔄 代替案
      description: 他に考えられる解決策があれば記入してください
      placeholder: 別のアプローチや既存の回避策など

  - type: textarea
    id: additional-context
    attributes:
      label: 📋 追加情報
      description: 参考資料、モックアップ、外部リンクなど
      placeholder: 関連するリンクやファイルがあれば記入してください

⚙️ テンプレート設定

設定ファイルの作成

# .github/ISSUE_TEMPLATE/config.yml
blank_issues_enabled: false
contact_links:
  - name: 💬 Q&A ディスカッション
    url: https://github.com/username/repo/discussions
    about: 質問がある場合はこちらをご利用ください
  - name: 📖 ドキュメント
    url: https://docs.example.com
    about: 使い方やAPIドキュメントはこちら

---

5. プロジェクトとの連携

📋 GitHub Projects 連携

Issueの自動プロジェクト追加

# .github/workflows/add-to-project.yml
name: Add Issue to Project
on:
  issues:
    types: [opened]

jobs:
  add-to-project:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/add-to-project@v0.4.0
        with:
          project-url: https://github.com/users/username/projects/1
          github-token: ${{ secrets.ADD_TO_PROJECT_TOKEN }}

ラベルベースの自動ワークフロー

# ラベルに応じて列を移動
name: Move Issue Based on Label
on:
  issues:
    types: [labeled]

jobs:
  move-issue:
    runs-on: ubuntu-latest
    if: github.event.label.name == 'in-progress'
    steps:
      - name: Move to In Progress
        uses: leonsteinhaeuser/project-beta-automations@v2.0.1
        with:
          gh_token: ${{ secrets.GITHUB_TOKEN }}
          user: username
          project_id: 1
          resource_node_id: ${{ github.event.issue.node_id }}
          status_value: "In Progress"

---

6. 自動化・効率化

🤖 GitHub Actions による自動化

Issue自動ラベリング

# .github/workflows/label-issues.yml
name: Auto Label Issues
on:
  issues:
    types: [opened]

jobs:
  label:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/labeler@v4
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}
          configuration-path: .github/labeler.yml

# .github/labeler.yml
"area:frontend":
  - "**/*.js"
  - "**/*.vue"
  - "**/*.css"

"area:backend":
  - "**/*.py"
  - "**/*.go"
  - "**/*.java"

"documentation":
  - "**/*.md"
  - "docs/**/*"

古いIssueの自動クローズ

# .github/workflows/stale-issues.yml
name: Close Stale Issues
on:
  schedule:
    - cron: '0 0 * * 0'  # 毎週日曜日

jobs:
  stale:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/stale@v8
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}
          stale-issue-message: |
            このIssueは60日間活動がありません。
            7日以内に活動がない場合、自動的にクローズされます。
          close-issue-message: |
            このIssueは非アクティブのため自動的にクローズされました。
          days-before-stale: 60
          days-before-close: 7

📊 Issue分析・レポート

CLI による統計取得

# Issue統計を取得するスクリプト
#!/bin/bash

echo "=== Issue Statistics ==="
echo "Total Issues: $(gh issue list --limit 1000 --json number | jq length)"
echo "Open Issues: $(gh issue list --state open --limit 1000 --json number | jq length)"
echo "Closed Issues: $(gh issue list --state closed --limit 1000 --json number | jq length)"

echo -e "\n=== Issues by Label ==="
gh issue list --limit 1000 --json labels | jq -r '.[].labels[].name' | sort | uniq -c | sort -nr

echo -e "\n=== Issues by Assignee ==="
gh issue list --limit 1000 --json assignees | jq -r '.[].assignees[].login' | sort | uniq -c | sort -nr

---

7. 外部ツールとの比較

📊 機能比較表

機能	GitHub Issues	Jira	Trello	Linear	備考
基本的なIssue管理	✅	✅	✅	✅	全て対応
カスタムフィールド	❌	✅	❌	✅	GitHubはラベルで代用
ワークフロー管理	⚠️	✅	⚠️	✅	GitHubはActionsで実現
時間トラッキング	❌	✅	⚠️	✅	外部サービス連携が必要
レポート機能	⚠️	✅	❌	✅	APIやInsightsを活用
マイルストーン	✅	✅	❌	✅	GitHubのマイルストーン機能
サブタスク	❌	✅	✅	✅	GitHubはタスクリストで代用
コード連携	✅	⚠️	❌	⚠️	GitHubが最も強力
コスト	無料〜	有料	無料〜	有料	GitHubがコスト効率良い

🔄 Jira からの移行

移行チェックリスト

✅ Issue種別 → ラベルでの分類方法決定
✅ ワークフロー → GitHub Projects V2 での再現
✅ カスタムフィールド → ラベルやマイルストーンでの代替
✅ レポート → GitHub API + スクリプトでの実現
✅ 時間管理 → 外部サービス連携の検討
✅ 権限管理 → リポジトリレベルでの設定調整

移行スクリプト例

# jira_to_github.py
import requests
import json

def migrate_issues(jira_url, github_repo, token):
    # Jira API からIssue取得
    jira_issues = fetch_jira_issues(jira_url)
    
    for issue in jira_issues:
        # GitHub Issue 形式に変換
        github_issue = {
            'title': issue['fields']['summary'],
            'body': convert_description(issue['fields']['description']),
            'labels': map_jira_labels(issue['fields']['labels'])
        }
        
        # GitHub API でIssue作成
        create_github_issue(github_repo, github_issue, token)

---

🎓 実践演習

演習1: Issue管理システム構築

1. バグ報告と機能要求のテンプレートを作成
2. 体系的なラベル分類を設計
3. マイルストーンを設定してIssueを分類

演習2: 自動化ワークフロー作成

1. 新しいIssueの自動ラベリング設定
2. 古いIssueの自動クローズ設定
3. プロジェクトボードとの連携設定

演習3: レポート・分析

1. Issue統計取得スクリプトの作成
2. 進捗レポートの自動生成
3. チームパフォーマンス分析

---

🔗 関連リソース

• GitHub Docs - Issues
• GitHub Issues Templates
• GitHub Projects Documentation
• GitHub CLI Issues

---

📝 まとめ

GitHub Issues を効果的に活用することで：

✅ 統一されたタスク管理 - 外部ツール不要でプロジェクト管理 ✅ コードとの密接な連携 - コミット・PRとのシームレスな連携 ✅ 自動化による効率化 - GitHub Actions による作業自動化 ✅ コスト削減 - 有料ツールからの移行によるコスト最適化 ✅ チーム協調 - 透明性の高い情報共有とコミュニケーション

次はPull Request編で、コードレビューとマージプロセスを学習しましょう。