À propos des crochets

Personnalisez et étendez le comportement de l’agent de GitHub Copilot en exécutant des commandes shell personnalisées aux moments clés de l’exécution de l’agent.

Qui peut utiliser cette fonctionnalité ?

Agent de codage Copilot est disponible avec les forfaits GitHub Copilot Pro, GitHub Copilot Pro+, GitHub Copilot Business et GitHub Copilot Enterprise. L'agent est disponible dans tous les référentiels stockés sur GitHub, à l'exception des référentiels appartenant à comptes d’utilisateur managés et où il a été explicitement désactivé.
Sign up for Copilot

Dans cet article

À propos des crochets

Les hooks vous permettent d’exécuter des commandes d’interpréteur de commandes personnalisées à des points stratégiques dans le workflow d’un agent, par exemple lorsque la session d’un agent démarre ou se termine, ou encore avant et après la saisie d’une invite ou l’appel d’un outil.

Les hooks reçoivent des informations détaillées sur les actions de l’agent via une entrée JSON, ce qui active l’automatisation prenant en charge le contexte. Par exemple, vous pouvez utiliser des hooks pour :

  • Approuvez ou refusez par programmation les exécutions d’outils.
  • Utilisez des fonctionnalités de sécurité intégrées telles que l’analyse secrète pour empêcher les fuites d’informations d’identification.
  • Implémentez des règles de validation personnalisées et la journalisation d’audit pour la conformité.

Copilot les agents supportent les hooks stockés dans des fichiers JSON dans votre référentiel à .github/hooks/*.json.

Les hooks peuvent être utilisés avec les éléments suivants :

  • Agent de codage Copilot sur GitHub
  • GitHub Copilot CLI dans le terminal

Types de hooks

Les types de crochets suivants sont disponibles :

  •         **sessionStart** : exécuté lorsqu’une nouvelle session d’agent commence ou lors de la reprise d’une session existante. Peut être utilisé pour initialiser des environnements, la session de journal démarre pour l’audit, valider l’état du projet et configurer des ressources temporaires.

  •         **sessionEnd** : exécuté lorsque la session de l’agent se termine ou est terminée. Peut être utilisé pour nettoyer les ressources temporaires, générer et archiver des rapports et des journaux de session, ou envoyer des notifications sur la fin de la session.

  •         **userPromptSubmitted** : exécuté lorsque l’utilisateur envoie une invite à l’agent. Peut être utilisé pour consigner les demandes utilisateur pour l’audit et l’analyse de l’utilisation. 

  •         **preToolUse** : exécuté avant que l’agent utilise n’importe quel outil (par exemple, `bash`, `edit`, `view`). Il s’agit du hook le plus puissant, car il peut **approuver ou refuser les exécutions d’outils**. Utilisez ce hook pour bloquer les commandes dangereuses, appliquer des stratégies de sécurité et des normes de codage, exiger l’approbation des opérations sensibles ou l’utilisation de l’outil de journalisation pour la conformité.

  •         **postToolUse** : exécuté après l’exécution d’un outil (réussite ou échec). Peut être utilisé pour consigner les résultats d’exécution, suivre les statistiques d’utilisation, générer des pistes d’audit, surveiller les métriques de performances et envoyer des alertes d’échec.

  •         **errorOccurred** : exécuté lorsqu’une erreur se produit pendant l’exécution de l’agent. Peut être utilisé pour consigner les erreurs de débogage, d’envoi de notifications, de suivi des modèles d’erreurs et de générer des rapports.

Pour afficher une référence complète des types de crochets avec des exemples de cas d’usage, des bonnes pratiques et des modèles avancés, consultez Configuration des hooks.

Format de configuration des hooks

Vous configurez des hooks à l’aide d’un format JSON spécial. Le code JSON doit contenir un version champ avec une valeur et 1 un hooks objet contenant des tableaux de définitions de hook.

JSON
{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "string (optional)",
        "powershell": "string (optional)",
        "cwd": "string (optional)",
        "env": { "KEY": "value" },
        "timeoutSec": 30
      }
    ],
  }
}

L’objet hook peut contenir les clés suivantes :

PropriétéObligatoireDescriptif
typeOuiDoit être "command"
bashOui (sur les systèmes Unix)Chemin d’accès au script bash à exécuter
powershellOui (sur Windows)Chemin d’accès au script PowerShell à exécuter
cwdNonRépertoire de travail du script (relatif à la racine du référentiel)
envNonVariables d’environnement supplémentaires fusionnées avec l’environnement existant
timeoutSecNonDurée d’exécution maximale en secondes (valeur par défaut : 30)

Exemple de fichier de configuration de hook

Il s’agit d’un exemple de fichier de configuration qui se trouve dans ~/.github/hooks/project-hooks.json un référentiel.

JSON
{
  "version": 1,
  "hooks": {
    "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
      }
    ],
    "userPromptSubmitted": [
      {
        "type": "command",
        "bash": "./scripts/log-prompt.sh",
        "powershell": "./scripts/log-prompt.ps1",
        "cwd": "scripts",
        "env": {
          "LOG_LEVEL": "INFO"
        }
      }
    ],
    "preToolUse": [
      {
        "type": "command",
        "bash": "./scripts/security-check.sh",
        "powershell": "./scripts/security-check.ps1",
        "cwd": "scripts",
        "timeoutSec": 15
      },
      {
        "type": "command",
        "bash": "./scripts/log-tool-use.sh",
        "powershell": "./scripts/log-tool-use.ps1",
        "cwd": "scripts"
      }
    ],
    "postToolUse": [
      {
        "type": "command",
        "bash": "cat >> logs/tool-results.jsonl",
        "powershell": "$input | Add-Content -Path logs/tool-results.jsonl"
      }
    ],
    "sessionEnd": [
      {
        "type": "command",
        "bash": "./scripts/cleanup.sh",
        "powershell": "./scripts/cleanup.ps1",
        "cwd": "scripts",
        "timeoutSec": 60
      }
    ]
  }
}

Considérations relatives aux performances

Les hooks s’exécutent de manière synchrone et bloquent l’exécution de l’agent. Pour garantir une expérience réactive, gardez à l’esprit les considérations suivantes :

  •         **Réduire le temps d’exécution : conservez le temps d’exécution** du hook sous 5 secondes lorsque cela est possible.

  •         **Optimiser la journalisation** : utilisez la journalisation asynchrone, comme l’ajout à des fichiers, plutôt que les E/S synchrones.

  •         **Utilisez le traitement en arrière-plan** : pour les opérations coûteuses, envisagez le traitement en arrière-plan.

  •         **Résultats du cache** : calculs coûteux en cache quand c’est possible.

Considérations relatives à la sécurité

Pour garantir que la sécurité est maintenue lors de l’utilisation de crochets, gardez à l’esprit les considérations suivantes :

  •         **Validez et assainissez toujours l’entrée traitée par des hooks**. Une entrée non approuvée peut entraîner un comportement inattendu.

  •           **Utilisez un échappement d’interpréteur de commandes approprié lors de la création des commandes**. Cela empêche les vulnérabilités d’injection de commandes.

  •         **Ne journalise jamais les données sensibles, telles que les jetons ou les mots de passe**.

  •           **Vérifiez que les scripts de hook et les journaux disposent des autorisations appropriées**. 

  •           **Soyez prudent avec les hooks qui effectuent des appels réseau externes**. Celles-ci peuvent introduire une latence, des défaillances ou exposer des données à des tiers.

  •         **Définissez les délais d’expiration appropriés pour empêcher l’épuisement des ressources**. Les hooks de longue durée peuvent bloquer l’exécution de l’agent et dégrader les performances.

Étapes suivantes

Pour commencer à créer des hooks, consultez Utilisation de hooks avec les agents de GitHub Copilot.