Usando ganchos com CLI do GitHub Copilot

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

Criar um gancho em um repositório em GitHub

1. Crie um novo hooks.json arquivo com o nome de sua escolha na .github/hooks/ pasta do repositório. O arquivo de configuração de ganchos deve estar presente no branch padrão do seu repositório para ser usado por Agente de codificação do Copilot. Para CLI do GitHub Copilot, os ganchos são carregados do diretório de trabalho atual.

2. 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": [...]
     }
   }
   

3. Configure a sintaxe do gancho nas chaves bash ou powershell, ou referencie diretamente os arquivos de script que você criou.

   • 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 Configuração de ganchos.

4. Confirme o arquivo no repositório e mescle-o no branch 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. No Windows, use o ConvertTo-Json -Compress comando 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

•         [AUTOTITLE](/copilot/reference/hooks-configuration)
  

•         [AUTOTITLE](/copilot/concepts/agents/coding-agent/about-coding-agent)
  

•         [AUTOTITLE](/copilot/concepts/agents/about-copilot-cli)
  

•         [AUTOTITLE](/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment)