GitHub Copilot エージェントを使ったフックの活用

フックを使用すると、エージェントの実行中にキー ポイントでカスタム シェル コマンドを実行することで、 GitHub Copilot エージェントの動作を拡張およびカスタマイズできます。 フックの概念の概要については、 フックについて を参照してください。

GitHub

のリポジトリにフックを作成する

1. リポジトリの hooks.json フォルダーに、任意の名前の新しい.github/hooks/ ファイルを作成します。 フック構成ファイルは、Copilot コーディング エージェント で使用するには、リポジトリの既定のブランチに 存在する必要があります 。 GitHub Copilot CLI（コマンドラインインターフェース） の場合、フックは現在の作業ディレクトリから読み込まれます。

2. テキスト エディターで、次のフック テンプレートをコピーして貼り付けます。 使用する予定のないフックを hooks 配列から削除します。

   JSON

   {
     "version": 1,
     "hooks": {
       "sessionStart": [...],
       "sessionEnd": [...],
       "userPromptSubmitted": [...],
       "preToolUse": [...],
       "postToolUse": [...],
       "errorOccurred": [...]
     }
   }
   

3.        `bash`キーまたは`powershell`キーでフック構文を構成するか、作成したスクリプト ファイルを直接参照します。 
   

   • 次の例では、 sessionStart フックを使用してセッションの開始日をログ ファイルに出力するスクリプトを実行します。

     JSON

     "sessionStart": [
       {
         "type": "command",
         "bash": "echo \"Session started: $(date)\" >> logs/session.log",
         "powershell": "Add-Content -Path logs/session.log -Value \"Session started: $(Get-Date)\"",
         "cwd": ".",
         "timeoutSec": 10
       }
     ],
     

   • 次の例では、外部 log-prompt スクリプトを呼び出します。

     JSON

     "userPromptSubmitted": [
       {
         "type": "command",
         "bash": "./scripts/log-prompt.sh",
         "powershell": "./scripts/log-prompt.ps1",
         "cwd": "scripts",
         "env": {
           "LOG_LEVEL": "INFO"
         }
       }
     ],
     

     エージェント セッションからの入力 JSON とサンプル スクリプトの完全なリファレンスについては、 フックの構成 を参照してください。

4. ファイルをリポジトリにコミットし、既定のブランチにマージします。 これで、フックはエージェント セッション中に実行されます。

トラブルシューティング

フックを使用して問題が発生した場合は、次の表を使用してトラブルシューティングを行います。

問題点	アクション
フックが実行されていない	JSON ファイルが .github/hooks/ ディレクトリ内にあるかどうかを確認します。 有効な JSON 構文 (たとえば、 jq . hooks.json) を確認します。

          `version: 1` ファイルに`hooks.json`が指定されていることを確認します。</li><li>フックから呼び出しているスクリプトが実行可能であることを確認します (`chmod +x script.sh`)</li><li>スクリプトに適切な shebang があることを確認します (例: `#!/bin/bash`)</li></ul> |

| フックがタイムアウトする |

• 既定のタイムアウトは 30 秒です。 必要に応じて、構成の timeoutSec を増やします。
• 不要な操作を回避してスクリプトのパフォーマンスを最適化します。
| | 無効な JSON 出力 |
• 出力が 1 行であることを確認します。
• Unix では、 jq -c を使用して JSON 出力を圧縮して検証します。
• Windows では、PowerShell の ConvertTo-Json -Compress コマンドを使用して同じ操作を行います。
|

デバッグ

次のメソッドを使用してフックをデバッグできます。

• スクリプトで詳細ログを有効化して、入力データを検査し、スクリプトの実行を追跡します。

  Shell

  #!/bin/bash
  set -x  # Enable bash debug mode
  INPUT=$(cat)
  echo "DEBUG: Received input" >&2
  echo "$INPUT" >&2
  # ... rest of script
  

•         **テストフックをローカルでテストするために、テスト入力をフックにパイプし**、その動作を検証します。
  

  Shell

  # Create test input
  echo '{"timestamp":1704614400000,"cwd":"/tmp","toolName":"bash","toolArgs":"{\"command\":\"ls\"}"}' | ./my-hook.sh
  
  # Check exit code
  echo $?
  
  # Validate output is valid JSON
  ./my-hook.sh | jq .
  

詳細については、次を参照してください。

• フックの構成の詳細については、フックの構成 を参照してください。
• Copilot コーディング エージェント の詳細については、GitHub Copilot コーディング エージェントについて を参照してください。
• GitHub Copilot CLI（コマンドラインインターフェース）の詳細については、GitHub Copilot CLI について を参照してください。
• エージェント環境のカスタマイズの詳細については、GitHub Copilot コーディング エージェント用の開発環境のカスタマイズ を参照してください。