🤖

Claude Code GitHub Actionsで実現する自動Issue解決システム

に公開
AI
GitHub Actions
自動化
Claude
Claude Code
tech

はじめに

「ーAIは便利だが、自分は結局、どのように使うのが便利なのだろう？」

私はこの問題解決のために、多くの時間を使っています。
AIを使った開発支援ツールは数多くありますが、その実例の多くはアプリケーション開発に特化しており、アプリケーション開発を行わない私の所属チームでは、そのまま取り込めるものがありませんでした。

「もっと汎用的、ベーシックな支援の仕組みがあれば、チームメンバーが自律的に使い方を見つけ、活用できるのではないか」と考え、Claude CodeとGitHub Actionsを組み合わせた「自動Issue解決システム」を構築してみました。

この記事では、Claude Code GitHub Actions（以下、CCGHA） と GitHub Actions（以下、GHA） を組み合わせて作成した「自動Issue解決システム」について、その仕組みから実装方法まで詳しく解説します。

こんな方にオススメ

  • GHAで開発フローを自動化したい方
  • Claudeを活用した事例を知りたい方
  • AIを使った開発支援システムに興味がある方
  • チーム開発の効率を向上させたい方

使ってみてどうか

まだ業務での導入はしていませんが、実際に動作することを確認できました。
とりあえず、以下の2点をIssueとして作成し、レポート作成から解決までを依頼しました。

  • CLAUDE.mdの作成
  • READMEの改修

プルリクエストのレビューでいくつか指示を出すことがありましたが、最終的にはマージまで行うことができました。

システムの概要

このシステムは、以下の2つのGHAワークフローで構成されています。

ワークフロー名 トリガー条件 主な機能
Issue分析ワークフロー analyze-issue ラベルが付与された時 - Issueの内容を分析
- 技術的な解決策を提案
- 詳細なレポートをIssueコメントに投稿
Issue解決ワークフロー Issueへのコメント（@claude メンション） - レポート内容を基にコード変更を実施
- プルリクエストを自動作成
- Issue作成者に通知

全体の流れ

人間とGHAがどのように連携してIssue解決まで進むのか、以下の図で確認してみましょう。

1. Issue分析ワークフロー（Analyzer）

GitHubでIssueにanalyze-issueラベルを付けると、CCGHAが自動的に起動して、次の処理を実行します。

  • 📋 リポジトリの現状を調査（コード、ドキュメント、テストの確認）
  • 🔍 Issueの内容を技術的に分析
  • 📊 実装の複雑さと成功率を評価（信頼度レベル：🟢高/🌕中/🔴低）
  • 📝 詳細な解決レポートをIssueコメントとして投稿
レポートをIssueコメントにした理由

当初はレポートをMarkdownファイルとして作成していましたが、以下の問題が発生したため、Issueコメントに直接投稿する方式に変更しました。

  1. レポートを作るCCGHAと、実装のCCGHA間で、レポートのMarkdownを容易に参照させられなかった（恐らくgithub-scriptを使えばできそうでしたが、複雑化させたくなかった）
  2. レポートが満足いく内容にならなかったときの指示方法が手間だった（Issueコメントであれば、Issue本文を修正してラベルを脱着すれば再実行できる）
信頼度レベルの導入理由

信頼度レベルは、Devinがこのような表現をしていると聞いたので導入しています。
どこまで使えるかは未知数ですが、指示の質の目安にはなると思います。

2. Issue解決ワークフロー（Resolver）

分析レポートを確認後、@claudeメンションでコメントすると、CCGHAが自動的に次の処理を実行します。

  • 👀 レポートの確認
  • 💻 必要なコード変更を実施
  • 🔄 プルリクエストを自動作成（URLで生成）
  • 📢 Issue作成者にメンションで通知

実際の動作フロー

では、実際にどのように動作するのか見てみましょう。

Step 1: Issueの作成とラベル付与

まず、通常通りGitHubでIssueを作成します。たとえば「ダークモード機能を追加したい」といった内容です。

# Issueタイトル: ダークモード機能の実装

## 概要
アプリケーションにダークモード切り替え機能を追加したい。

## 要件
- ヘッダーにトグルボタンを配置
- ユーザーの選択を保存
- システムの設定に従うオプション

作成したIssueにanalyze-issueラベルを付けると、自動分析が開始されます。

Step 2: 自動分析とレポート生成

数分後、CCGHAが以下のようなレポートをコメントとして投稿します。

## 🟢 調査レポートが完成しました

@username Issueの調査と解決計画を作成しました。

📄 **レポート**:

# Issue #123 解決レポート

**作成日時**: 2024-12-27 10:30:00
**Issue**: ダークモード機能の実装
**信頼度**: 🟢 高

## 1. Issue概要
ユーザーがライト/ダークモードを切り替えられる機能の実装要求です。

## 2. 現状分析
- 現在のアプリケーションはライトモードのみ対応
- CSS変数を使用した実装が可能
- LocalStorageを使用してユーザー設定を保存可能

## 3. 解決アプローチ
1. CSS変数を使用したテーマシステムの構築
2. React Contextでテーマ状態を管理
3. トグルコンポーネントの実装
4. LocalStorageへの永続化

## 4. 実装計画
1. テーマ用CSS変数の定義
2. ThemeContextとProviderの作成
3. トグルボタンコンポーネントの実装
4. 既存コンポーネントへのテーマ適用
5. テストの追加

## 5. 注意事項
- アクセシビリティの考慮が必要
- 初回ロード時のちらつき対策
- システム設定との連携実装

## 6. テスト計画
- ユニットテスト：テーマ切り替えロジック
- E2Eテスト：ユーザー操作フロー
- ビジュアルリグレッションテスト

レポートに問題がなければ、このレポートをコピーして、Issueの本文に追記します。
この後の実装指示でClaudeが読み取ってくれます。

Step 3: 実装の承認と自動開発

@claudeメンションつきでコメントします。

@claude このIssueを解決してください。

メンションを検知すると、CCGHAが自動的に実装を開始し、プルリクエスト作成リンクの発行までを行ってくれます。

Step 4: プルリクエストの確認とマージ

プルリクエストを作成したら、人間が内容を確認します。
何か問題があれば、@claudeメンションを付けてコメントで指摘することで、再度CCGHAが実装を行います。

セットアップ方法

このシステムを自分のリポジトリに導入するときは、次の手順でセットアップします。

前提条件

  • GitHubリポジトリの管理者権限
  • GitHub Appsのインストール（公式またはカスタムアプリ。詳しくは公式ドキュメントを参照）
  • Claude Code OAuthトークン（Claude Codeから取得）

1. ワークフローファイルの追加

2つのワークフローファイルをリポジトリに追加します。

.GitHub/workflows/claude-issue-analyzer.yml
.github/workflows/claude-issue-analyzer.yml
name: Claude Issue Analyzer

# トリガー条件: analyze-issueラベルが付与された時
on:
  issues:
    types: [labeled]

# 必要な権限を設定
permissions:
  issues: write          # Issue操作権限
  contents: write        # リポジトリ内容変更権限
  pull-requests: write   # プルリクエスト作成権限
  actions: write         # ワークフロー実行権限

jobs:
  analyze-issue:
    name: Analyze Issue with CCGHA
    runs-on: ubuntu-latest
    # analyze-issueラベルが付与された時のみ実行
    if: github.event.label.name == 'analyze-issue'
    steps:
      # Step 1: リポジトリをチェックアウト
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 全履歴を取得（ブランチ作成のため）

      # Step 2: CCGHAによる Issue分析とレポート作成
      - name: Analyze issue with Claude
        uses: anthropics/claude-code-action@beta
        with:
          label_trigger: analyze-issue
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
          mcp_config: |
            {
              "mcpServers": {
                "Context7": {
                  "command": "npx",
                  "args": ["-y", "@upstash/context7-mcp"]
                }
              }
            }
          allowed_tools: >-
            mcp__Context7__resolve-library-id
            mcp__Context7__get-library-docs
          override_prompt: |
            # Issue分析タスク

            あなたはソフトウェアエンジニアリングの専門家です。Issue #$ISSUE_NUMBER を分析し、レポートをコメント欄へ直接記入してください。

            ## Issue情報
            - **タイトル**: $ISSUE_TITLE
            - **内容**: $ISSUE_BODY
            - **作成者**: $TRIGGER_USERNAME

            ## タスク
            1. リポジトリの現状を分析する（既存のコード、ドキュメント、テストの確認）
            2. Issueの内容を理解し、技術的な解決アプローチを検討する(use context7)
            3. 実装の複雑さと成功率を評価する
            4. 下記のフォーマットで Issueコメントを作成する

            ## レポートフォーマット
            [省略 - 実際のファイルを参照]
.GitHub/workflows/claude-issue-resolver.yml
.github/workflows/claude-issue-resolver.yml
name: Claude Issue Resolver

# トリガー条件: Issueへのコメント＆プルリクエストレビューコメント
on:
  issues:
    types: [opened]
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

# 必要な権限を設定
permissions:
  issues: write          # Issue操作権限
  contents: write        # リポジトリ内容変更権限
  pull-requests: write   # プルリクエスト作成権限
  actions: write         # ワークフロー実行権限

jobs:
  resolve-issue:
    name: Resolve Issue with CCGHA
    runs-on: ubuntu-latest
    # IssueまたはPRに@claude メンションが付いたコメントが追加された時
    if: |
      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'issues' && contains(github.event.issue.body, '@claude'))
    steps:
      # Step 1: リポジトリをチェックアウト
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 全履歴を取得（ブランチ作成のため）

      # Step 2: CCGHAによる Issue解決
      - name: Resolve issue with Claude
        uses: anthropics/claude-code-action@beta
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
          mcp_config: |
            {
              "mcpServers": {
                "Context7": {
                  "command": "npx",
                  "args": ["-y", "@upstash/context7-mcp"]
                }
              }
            }
          allowed_tools: >-
            mcp__Context7__resolve-library-id
            mcp__Context7__get-library-docs
          custom_instructions: |
            私との会話は日本語でお願いします。

2. シークレットの設定

GitHubリポジトリの設定画面から、次の手順でシークレットを追加します。

  1. Settings → Secrets and variables → Actions
  2. New repository secret をクリック
  3. 次の項目を設定します
    • Name: CLAUDE_CODE_OAUTH_TOKEN
    • Secret: Claude Codeから取得したOAuthトークン

3. 権限の確認

Settings → Actions → General → Workflow permissions で次の項目を確認します

  • ✅ "Read and write permissions" が選択されていること
  • ✅ "Allow GHA to create and approve pull requests" にチェック

これで設定は完了です。

応用

今後このシステムを拡張する場合、以下のような応用が考えられます。

  1. 未着手Issueの自動検出とラベル付与
    • タイマースケジュールなどで、ラベル未設定のIssueにanalyze-issueラベルを自動で付与するワークフローを追加すると、CCGHAに依頼する対象を増やすことができます。
    • もしIssueの特性的にAIに適していなかったとしても、レポートが人間の調査負荷を減らしてくれるなら、それだけでも意味はありそうです。

まとめ

CCGHAとGHAを組み合わせることで、Issueの作成から解決までを自動化するシステムを構築しました。
ただし、業務への導入はこれからのため、実際の効果や課題については、今後の運用を通じて検証していく予定です。

今後やりたいこと

  • 実務での検証とアップデート
  • CCGHAの機能拡張に合わせたアップデート
  • リポジトリ外のナレッジを渡せる手段の実装

参考リンク

Discussion