Utiliser les workflows

Apprenez à utiliser les workflows Mintlify pour automatiser les tâches récurrentes de maintenance de contenu, choisir le type de trigger adapté, rédiger des instructions efficaces et obtenir des résultats cohérents.

Les workflows exécutent l’agent automatiquement afin que votre contenu reste exact sans effort manuel. Ce guide explique comment choisir le bon workflow, le configurer efficacement et rédiger des instructions qui produisent des résultats cohérents.

​

Quand utiliser les workflows

Les workflows conviennent particulièrement aux tâches qui sont :

• Répétitives — La même tâche s’exécute régulièrement selon une planification prévisible ou chaque fois qu’un événement spécifique se produit.
• Chronophages — Des tâches longues à effectuer manuellement mais qui suivent un schéma cohérent.
• Réactives — Des tâches qui doivent se déclencher automatiquement en réponse à des changements de code ou de contenu, comme la mise à jour de la documentation après la livraison d’une fonctionnalité.

Pour des tâches ponctuelles ou exploratoires, utilisez l’agent directement dans le tableau de bord ou depuis Slack.

​

Choisir un trigger

Chaque workflow s’exécute avec l’un des trois types de trigger. Choisissez celui qui correspond au moment où vous avez besoin que le travail soit effectué.

Trigger	À utiliser quand
Mise à jour de contenu	La tâche doit s’exécuter chaque fois que le contenu de votre projet change — traduire de nouvelles pages, corriger des liens rompus ou auditer les métadonnées SEO.
Changement de code	La tâche doit s’exécuter lorsque le code source change — mettre à jour les spécifications d’API ou la documentation après la fusion d’une PR.
Planification personnalisée	La tâche doit s’exécuter à une cadence fixe quoi qu’il arrive — publier des changelogs hebdomadaires ou exécuter des vérifications grammaticales périodiques.

​

Workflows prédéfinis

Mintlify inclut des workflows prédéfinis pour les tâches de maintenance de contenu les plus courantes. Activez l’un d’entre eux depuis la page Workflows de votre tableau de bord.

Consultez Workflows prédéfinis pour plus de détails.

​

Workflows personnalisés

Créez un workflow personnalisé pour les tâches qui ne sont pas couvertes par les options prédéfinies. Les workflows personnalisés vous donnent un contrôle total sur le trigger, les instructions et les dépôts de contexte.

Consultez Créer un workflow personnalisé pour les étapes de configuration.

​

Rédiger des instructions efficaces

Les instructions d’un workflow personnalisé sont des prompts que l’agent suit à chaque exécution. La qualité de vos instructions affecte directement la cohérence des résultats.

Décrivez le résultat, pas seulement la tâche. Indiquez à l’agent à quoi ressemble un travail terminé.

Moins efficace

Examinez les pages de référence de l'API.

Rédigez une procédure. Les agents suivent des instructions étape par étape de manière plus fiable que des prompts ouverts.

Exemple de procédure

1. Lisez le diff de la pull request fusionnée du dépôt déclencheur.
2. Identifiez les endpoints, paramètres ou formes de réponse de l'API qui ont changé.
3. Recherchez dans la documentation les pages qui font référence à ces endpoints.
4. Mettez à jour les pages concernées pour qu'elles correspondent aux changements de la pull request.
5. Ouvrez une pull request avec un résumé des pages que vous avez modifiées et pourquoi.

Limitez le périmètre. Un workflow qui fait une chose bien est plus fiable qu’un workflow qui essaie d’en faire plusieurs. Répartissez les tâches complexes entre plusieurs workflows.

Spécifiez les fichiers et les répertoires. Plus vous êtes précis sur l’endroit où l’agent doit chercher, moins il passe de temps à explorer.

Exemple avec des chemins spécifiques

Vérifiez chaque fichier MDX du répertoire /content pour repérer les liens internes rompus (liens commençant par /).
Pour chaque lien rompu, corrigez le chemin ou supprimez le lien s'il n'existe pas de remplacement.

​

Utiliser des dépôts de contexte

Pour les workflows personnalisés et certains workflows prédéfinis, vous pouvez ajouter des dépôts de contexte que l’agent lit lors de l’exécution du workflow.

Ajoutez des dépôts de contexte lorsque :

• Votre contenu fait référence à du code, à des APIs ou à de la configuration qui se trouvent dans un dépôt distinct.
• Vous souhaitez que l’agent compare votre contenu au code source lorsqu’il décide de ce qu’il doit mettre à jour.
• Le prompt du workflow fait référence à des fichiers en dehors du dépôt de votre projet Mintlify.

Vous pouvez ajouter jusqu’à 10 dépôts de contexte par workflow.

​

Mode de mise à jour

Décidez du niveau de revue que vous souhaitez avant la publication des changements.

• Automatique : Les changements sont fusionnés directement dans le dépôt de votre projet Mintlify sans revue. Idéal pour des tâches à faible risque et haute fréquence comme la traduction, les vérifications grammaticales et la correction de liens.
• Exiger une revue : L’agent ouvre une pull request et une personne la relit avant la fusion. Idéal pour les tâches qui modifient le sens du contenu, comme la synchronisation avec les changements de code ou la mise à jour des références d’API.

​

Contrôler l’utilisation des crédits

Chaque exécution de workflow consomme des crédits. Par exemple, la plupart des exécutions du workflow mettre à jour à partir des changements de code coûtent entre 40 et 180 crédits. Les exécutions complexes qui mettent à jour de nombreuses pages coûtent davantage.

Planifier des tâches cron pour qu’elles s’exécutent à des moments précis vous permet de contrôler plus finement l’utilisation des crédits. Par exemple, vous pouvez exécuter un workflow une fois par jour ou une fois par semaine pour savoir exactement combien de pull requests un workflow crée par mois, plutôt que d’avoir une variation mensuelle en fonction des changements de contenu ou de code.

​

Examiner et améliorer les résultats des workflows

Les workflows s’exécutent automatiquement, mais ils gagnent à être examinés périodiquement.

1. Ouvrez l’onglet Runs de la page Workflows pour voir l’historique récent des exécutions et leur statut.
2. Cliquez sur une exécution pour lire le résumé de l’agent et examiner les pull requests qu’il a ouvertes.
3. Si les résultats sont incohérents, affinez vos instructions : ajoutez des procédures plus précises, réduisez la portée des fichiers ou répartissez le workflow en tâches plus petites.

Quelques cycles de revue après l’activation d’un nouveau workflow suffisent généralement à affiner les instructions.