Filtres d'entrée et prévisualisation
Filtres d'entrée et prévisualisation
Ciblez précisément les événements qui déclenchent un AgentHook et vérifiez les résultats avant activation
Affinez les branches, fichiers et auteurs qui déclenchent vos hooks. Testez la configuration avec “Preview documents” pour voir des exemples concrets avant de mettre en production.
Ce que vous apprendrez
Filtrer les inputs entrants
Apprenez à cibler par branche, motif de fichier (globs / presets) et auteur pour ne traiter que les événements pertinents.
Choisir les destinations de sortie
Recevoir les documents générés par e-mail, envoyer vers des webhooks externes, ou les deux pour combiner revue humaine et automatisation.
Prévisualiser avant activation
Utilisez la fonction “Preview documents” pour générer exemples basés sur vos filtres et corriger la configuration sans lancer d’exécutions réelles.
Introduction
Ce guide détaillé explique, étape par étape, comment configurer les filtres d’entrée d’un AgentHook (branches, fichiers, auteurs), comment choisir où envoyer les sorties (e‑mail et/ou webhooks), et comment utiliser la prévisualisation des documents pour tester la configuration avant d’activer un hook. Vous trouverez des workflows pratiques, des astuces, des mises en garde et une FAQ pour les cas avancés.
Rappel important
Les fréquences sont exprimées par paire (frequency_count, frequency_duration) et déterminent la prochaine date d’exécution calculée côté serveur. Les hooks programmés sont exécutés par des workers et peuvent être désactivés en modifiant ou supprimant le hook. L’exécution des agents peut consommer des crédits — surveillez votre solde avant de lancer des tests massifs.
Workflow A — Configurer les filtres d'entrée (branches, fichiers, auteurs)
Étape 1 — Ouvrir la configuration du hook
Accédez à la page de création/modification d’un AgentHook depuis la section “Hooks d’automatisation”. Ouvrez le dialogue de configuration du hook que vous voulez paramétrer.
Étape 2 — Choisir le type d'événement
Sélectionnez le déclencheur souhaité (ex. push, pull request, branche spécifique, ou exécution planifiée). Cela définit le contexte dans lequel vos filtres seront évalués.
Étape 3 — Ajouter un filtre de branche
- Indiquez une branche précise (ex. main) ou un motif (préfixe comme feature/*).
- Pour un contrôle fin, utilisez des expressions littérales ou des caractères génériques si l’interface le permet.
- Conseil pratique : commencez par une branche de test pour éviter les déclenchements en production.
Étape 4 — Ajouter un filtre de fichiers
- Utilisez des motifs de type glob (ex. src/**/*.ts, README.md) ou sélectionnez des presets linguistiques (ex. “Documentation”, “Vue”, “Python”) si disponibles.
- Excluez les répertoires communs (node_modules, build, dist) pour éviter le bruit.
- Si vous souhaitez cibler uniquement certains types de modifications (par ex. fichiers README), précisez ces motifs.
Étape 5 — Filtrer par auteur
- Indiquez une liste d’auteurs (adresse e‑mail ou nom d’utilisateur) pour ne réagir qu’aux contributions de certains collaborateurs ou bots.
- Pour des tests, ajoutez uniquement votre propre compte afin d’isoler le comportement.
Étape 6 — Combiner et valider les filtres
- Les filtres s’appliquent de façon cumulative : chaque critère restreint davantage les événements (par défaut comportement restrictif).
- Vérifiez s’il existe une option de mode de correspondance (AND vs OR) et ajustez selon le besoin.
- Enregistrez la configuration temporairement comme “brouillon” si l’interface propose cette option.
Étape 7 — Sauvegarder sans activer (optionnel)
Si vous voulez tester d’abord en toute sécurité, enregistrez le hook sans l’activer et passez à la prévisualisation.
Astuce — Utiliser des presets pour les fichiers
Si l’interface propose des presets (ex. “Documentation”, “Vue”, “Python”), utilisez-les : ils contiennent des motifs d’inclusion/exclusion optimisés et évitent d’oublier des formats fréquents.
Workflow B — Choisir les destinations de sortie (e‑mail et webhooks)
Étape 1 — Ouvrir la section Destinations
Dans la configuration du hook, recherchez la section “Destinations” ou “Outputs”. C’est ici que vous définissez où envoyer les documents générés.
Étape 2 — Activer l'envoi par e‑mail
- Cochez l’option e‑mail si vous voulez envoyer des exemples ou résultats aux relecteurs.
- Indiquez une ou plusieurs adresses destinataires, ou un groupe d’équipe.
- Pour les revues humaines, demandez un résumé dans le sujet et/ou le corps pour faciliter l’évaluation.
Étape 3 — Ajouter un Webhook externe
- Sélectionnez un endpoint webhook existant ou créez-en un nouveau (nom, URL, méthode, headers).
- Configurez la signature ou l’authentification si nécessaire (HMAC, token).
- Activez les options de retry et de backoff si disponibles pour garantir la livraison en cas d’échec temporaire.
Étape 4 — Combiner e‑mail et webhook
Vous pouvez recevoir à la fois des e‑mails pour revue humaine et poster des payloads vers des webhooks pour intégration automatisée (CI, Notion, Slack).
Étape 5 — Valider les formats envoyés
Vérifiez si l’option d’envoyer le document en texte brut, JSON ou attaché est disponible, et choisissez le format adapté aux consommateurs.
Étape 6 — Sauvegarder les destinations
Sauvegardez vos destinations. Vous pourrez revenir les modifier sans toucher aux filtres.
Astuce — Dualisez pour sécurité
Envoyer à la fois un e‑mail (revue humaine) et un webhook (automatisation) pendant la phase de test permet de détecter rapidement les faux positifs avant de basculer en entièrement automatique.
Workflow C — Prévisualiser les documents générés (Preview documents)
Étape 1 — Lancer la prévisualisation
Trouvez et cliquez sur “Preview documents” dans la fiche du hook ou la boîte de dialogue d’édition. Cette fonction génère des exemples basés sur vos filtres et les commits récents.
Étape 2 — Configurer la taille et la période d'échantillonnage
Choisissez le nombre d’exemples que vous souhaitez voir (ex. 5–20) et, si l’option est disponible, la période (derniers 7 jours, 30 jours, etc.).
Étape 3 — Analyser les documents retournés
Pour chaque document exemple, vérifiez :
- le contenu généré (qualité, pertinence),
- le contexte (branche, fichier, auteur, message de commit),
- le pas d’agent ou prompt utilisé (si visible). Prenez des notes sur les faux positifs/nécessités d’ajustement.
Étape 4 — Affiner les filtres
Si des documents indésirables apparaissent :
- resserrez les motifs de fichiers,
- ajoutez ou excluez des auteurs,
- restreignez la branche ou ajoutez conditions supplémentaires. Relancez la prévisualisation après chaque modification.
Étape 5 — Vérifier l'impact estimé
Estimez le volume d’exécution attendu (fréquence × nombre de correspondances) pour anticiper consommation de crédits. Si l’outil affiche un compteur estimé, utilisez-le.
Étape 6 — Valider avant activation
Quand les exemples sont satisfaisants, activez le hook avec confiance. Sinon, recommencez l’affinage.
Attention — Ne testez pas à grande échelle par défaut
Générer de nombreux exemples ou activer un hook sur une branche très active peut provoquer une forte consommation de crédits et de requêtes vers vos destinations. Toujours commencer par un petit échantillon et une branche de test.
- Utilisation : générer notes ou documents dès qu’une branche feature/ reçoit des commits.
- Filtre recommandé : branche = feature/*, fichiers = src/** ou docs/** selon besoin, auteur = toute l’équipe ou exclure bots.
- Astuce : limitez les motifs de fichiers pour ne pas traiter les simples corrections de style.
Avant : vous activez un hook sans test → risque d’alertes indésirables, de consommation de crédits imprévue, et de notifications inutiles.
Après : vous utilisez les filtres + Preview documents → vous activez uniquement quand les exemples sont conformes, et vous minimisez les faux positifs.
Astuce avancée — Éviter les boucles de déclenchement
Si vos agents modifient le dépôt (p.ex. ajout de fichiers ou mises à jour automatiques), veillez à exclure les chemins ou l’auteur utilisé par l’agent pour éviter des boucles où le hook se réactive indéfiniment.
Astuce pour motifs de fichiers
- Utilisez des motifs inclusifs pour cibler précisément (ex. src/components/**) et des motifs d’exclusion pour ignorer l’infrastructure (node_modules, build).
- Pour les fichiers de documentation, les presets README/CHANGELOG sont souvent suffisants.
Limites et erreurs fréquentes
- Vérifiez le mode de combinaison des filtres : un filtre trop permissif combiné à un autre permissif peut laisser passer trop d’événements.
- Un webhook mal configuré (URL invalide, auth manquante) provoquera des échecs répétés ; activez la journalisation et les retries.
- Les hooks planifiés sont exécutés par des workers : si un worker est occupé ou stoppé, les exécutions peuvent être retardées.
Workflow D — Activer, surveiller et désactiver un hook en toute sécurité
Étape 1 — Activer le hook après tests
Activez le hook uniquement après que la prévisualisation donne des résultats satisfaisants.
Étape 2 — Surveiller les premières exécutions
Après activation, surveillez les premières runs : contrôlez les documents créés, les e‑mails envoyés et les requêtes webhook.
Étape 3 — Contrôler la consommation de crédits
Vérifiez l’impact sur votre solde de crédits après les premières exécutions. Ajustez fréquence ou filtres si la consommation est excessive.
Étape 4 — Désactiver / modifier si nécessaire
Si comportement inattendu : désactivez le hook ou modifiez les filtres/destinations. La suppression ou modification arrête les exécutions programmées.
Étape 5 — Itérer
Réitérez le cycle prévisualisation → ajustement → activation jusqu’à atteindre le comportement désiré.
Frequently Asked Questions
Prêt à tester vos filtres ?
Lancez un Preview documents avec un petit échantillon (5–10) sur une branche de test pour valider la configuration avant de passer en production.
Fin.