Usando ganchos com CLI do GitHub Copilot

Os ganchos permitem estender e personalizar o comportamento dos agentes executando comandos de shell personalizados em pontos-chave durante a execução do GitHub Copilot agente. Para obter uma visão geral conceitual dos ganchos, incluindo detalhes dos gatilhos disponíveis para os ganchos, consulte Sobre ganchos para GitHub Copilot.

Criando um gancho em um repositório em GitHub

1. No editor de texto, copie e cole o modelo de gancho a seguir. Remova os ganchos que você não planeja usar da hooks matriz.

   JSON

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

2. Configure a sintaxe do gancho nos campos das chaves bash e powershell, ou referencie diretamente os arquivos de script que você criou.

   Observação

   Inclua uma chave bash (com um script para Linux e macOS) e uma chave powershell (para um script para Windows) para permitir que os ganchos sejam executados em todos os três sistemas operacionais. Copilot usa a chave apropriada com base no sistema operacional do usuário.

   • Este exemplo executa um script que gera a data de início da sessão para um arquivo de log usando o sessionStart gancho:

     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
       }
     ],
     

   • Este exemplo chama um script externo log-prompt:

     JSON

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

     Para obter uma referência completa do JSON de entrada das sessões de agente, juntamente com scripts de exemplo, consulte Referência dos hooks do GitHub Copilot.

3. Confirme o arquivo no repositório e faça a mesclagem na ramificação padrão. Agora, os ganchos serão executados durante as sessões do agente.

Resolução de problemas

Se você encontrar problemas ao usar hooks, utilize a tabela a seguir para solucioná-los.

Questão	Ação
Os ganchos não estão sendo executados	Verifique se o arquivo JSON está no .github/hooks/ diretório. Verifique se há uma sintaxe JSON válida (por exemplo, jq . hooks.json). Verifique se version: 1 está especificado em seu hooks.json arquivo. Verifique se o script chamado pelo gancho é executável (chmod +x script.sh) Verifique se o script tem um shebang adequado (por exemplo, #!/bin/bash)
Ganchos estão atingindo o tempo limite	O tempo limite padrão é 30 segundos. Aumente timeoutSec na configuração, se necessário. Otimize o desempenho do script evitando operações desnecessárias.
Saída JSON inválida	Verifique se a saída está em uma única linha. No Unix, use jq -c para compactar e validar a saída JSON. Em Windows, use o comando ConvertTo-Json -Compress no PowerShell para fazer o mesmo.

Resolução de Erros

Você pode depurar ganchos usando os seguintes métodos:

• Habilite o log detalhado no script para inspecionar os dados de entrada e rastrear a execução do script.

  Shell

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

• Teste ganchos localmente canalizando a entrada de teste para o seu gancho para validar seu comportamento.

  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 .
  

Leitura adicional

• Referência dos hooks do GitHub Copilot
• Sobre o agente de nuvem do GitHub Copilot
• Sobre GitHub Copilot CLI
• Configurar o ambiente de desenvolvimento
• Referência dos hooks do GitHub Copilot