Utilisation des hooks avec GitHub Copilot CLI

Les hooks vous permettent d’étendre et de personnaliser le comportement des agents GitHub Copilot en exécutant des commandes shell personnalisées aux points clés durant l'exécution de l'agent. Pour obtenir une vue d’ensemble conceptuelle des hooks, y compris les détails des déclencheurs de hook disponibles, consultez À propos des crochets.

Création d’un hook dans un référentiel sur GitHub

Créez un hooks.json fichier avec le nom de votre choix dans le .github/hooks/ dossier de votre dépôt. Le fichier de configuration des hooks doit être présent sur la branche par défaut de votre référentiel à utiliser par Agent de programmation Copilot. Pour GitHub Copilot CLI, les hooks sont chargés à partir de votre répertoire de travail actuel.

Dans votre éditeur de texte, copiez et collez le modèle de hook suivant. Supprimez les éléments que vous ne prévoyez pas d’utiliser dans le tableau hooks.

JSON

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

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

Configurez votre syntaxe de hook sous les clés bash ou powershell, ou référencez directement les fichiers de script que vous avez créés.

Cet exemple exécute un script qui génère la date de début de la session dans un fichier journal à l’aide du sessionStart hook :

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

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

Cet exemple appelle un script externe log-prompt :

JSON

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

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

Pour obtenir une référence complète sur l’entrée JSON à partir de sessions d’agent, ainsi que des exemples de scripts, consultez Configuration des hooks.

Validez le fichier dans le référentiel et fusionnez-le dans la branche par défaut. Vos hooks s’exécuteront désormais pendant les sessions de l’agent.

Résolution des problèmes

Si vous rencontrez des problèmes lors de l’utilisation des hooks, utilisez le tableau suivant pour les diagnostiquer et les résoudre.

Problème	Action
Les hooks ne s’exécutent pas	Vérifiez que le fichier JSON se trouve dans le `.github/hooks/` répertoire. Recherchez la syntaxe JSON valide (par exemple). `jq . hooks.json` **

Assurez-vous que version: 1 est spécifié dans le fichier hooks.json.

Vérifiez que le script que vous appelez à partir de votre hook est exécutable (chmod +x script.sh)

Vérifiez que le script contient un shebang approprié (par exemple, #!/bin/bash)

| | Les hooks expirent |

Le délai d’expiration par défaut est de 30 secondes. Augmentez timeoutSec dans la configuration si nécessaire.
Optimisez les performances des scripts en évitant les opérations inutiles.

| | Sortie JSON non valide |

Vérifiez que la sortie se trouve sur une seule ligne.
Sur Unix, utilisez jq -c pour compacter et valider la sortie JSON.
Sur Windows, utilisez la ConvertTo-Json -Compress commande dans PowerShell pour effectuer la même opération.

Débogage

Vous pouvez déboguer des hooks à l’aide des méthodes suivantes :

        **Activez la journalisation détaillée** dans le script pour inspecter les données d’entrée et tracer l'exécution du script.

Shell

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

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

        **Testez les hooks localement** en redirigeant l’entrée de test dans votre hook pour valider son comportement :

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 .

# 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 .

Lectures complémentaires

        [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)

Dans cet article

Création d’un hook dans un référentiel sur GitHub

Résolution des problèmes

Débogage

Lectures complémentaires