Workflows

Automatisez la maintenance de votre documentation avec des tâches d’agent planifiées ou déclenchées par des événements.

Les workflows sont en bêta. Ils sont actuellement disponibles sur les offres Enterprise.

Contactez-nous pour activer les workflows au sein de votre organisation.

Les workflows exécutent l’agent automatiquement selon un calendrier défini ou lorsqu’un push est effectué sur un référentiel. Chaque workflow définit un prompt pour l’agent et un déclencheur indiquant quand l’exécuter.

Lorsqu’un workflow s’exécute, l’agent clone tous les référentiels spécifiés comme contexte, suit le prompt, puis soit ouvre une pull request (demande de fusion), soit pousse directement les modifications vers votre branche de déploiement.

Vous pouvez avoir jusqu’à 10 workflows actifs. Chaque workflow peut s’exécuter jusqu’à 20 fois par jour. Les exécutions qui échouent ne sont pas comptabilisées dans cette limite.

Utilisez des workflows exécutés selon un calendrier pour automatiser des tâches récurrentes telles que la publication du journal des modifications ou la détection de problèmes de grammaire et de style.

Utilisez des workflows exécutés sur des événements de push pour automatiser des tâches de maintenance réactive telles que la mise à jour des références d’API ou l’identification des mises à jour de documentation nécessaires pour de nouvelles fonctionnalités.

​

Créer un workflow

​

Créer un workflow dans le Dashboard

Sur la page Workflows de votre Dashboard, cliquez sur le bouton New workflow.

​

Ajouter un fichier de workflow à votre référentiel

Créez un fichier .md pour chaque workflow dans un répertoire .mintlify/workflows/ situé à la racine de votre référentiel de documentation. Chaque fichier correspond à un workflow.

Les fichiers de workflow utilisent le frontmatter YAML pour configurer le workflow, suivi d’un prompt en Markdown pour l’agent.

.mintlify/workflows/update-changelog.md

---
name: Update changelog
on:
  cron: "0 9 * * 1"
context:
  - repo: your-org/your-product
automerge: false
---

Review all changes since the last changelog update. Draft a new changelog post with any new features, bug fixes, or breaking changes.

Include information about what a change is and how it affects users.

Do not include any internal-only information or minor changes like bumping package versions or updating documentation.

Success criteria: Someone who reads the changelog knows the most up to date information about the product including what changed and whether or not it affects them.

​

Champs de frontmatter

Champ	Obligatoire	Description
name	Oui	Nom d’affichage visible dans le Tableau de bord Mintlify.
on	Oui	Configuration du déclencheur.
context	Non	Référentiels clonés à titre de référence lors de l’exécution du workflow.
automerge	Non	La valeur par défaut est false, ce qui ouvre une pull request (demande de fusion). Si true, pousse les modifications directement vers votre branche de déploiement.

Vous devez avoir installé la GitHub App Mintlify sur chaque référentiel répertorié dans les champs context ou on.push.repo. Ajoutez de nouveaux référentiels sur la page GitHub App de votre Tableau de bord Mintlify.

​

Déclencheurs

Chaque flux de travail doit définir un seul déclencheur en utilisant le champ on.

​

Selon une planification (cron)

Exécutez un workflow à intervalles réguliers à l’aide d’une expression cron. Toutes les planifications s’exécutent en UTC.

Les workflows sont placés en file d’attente dans les 10 minutes suivant l’heure planifiée et leur exécution peut prendre jusqu’à 10 minutes.

on:
  cron: "0 9 * * 1"

La valeur est une expression cron standard à 5 champs au format minute hour day-of-month month day-of-week. Utilisez un outil comme crontab.guru pour définir et valider les programmations.

Expression	Planification
"0 9 * * 1"	Chaque lundi à 9 h 00 UTC
"0 0 1 * *"	Premier jour de chaque mois à 0 h 00 UTC
"0 8 * * 1-5"	Du lundi au vendredi à 8 h 00 UTC

​

Lors des événements de type push

Exécutez un workflow lorsque des modifications sont poussées vers un référentiel et une branche spécifiques. Cela inclut les fusions de pull requests et les poussées directes vers la branche.

on:
  push:
    - repo: your-org/your-product
      branch: main

• repo: Le référentiel GitHub au format owner/repo.
• branch (facultatif) : la branche à surveiller pour les poussées. Si vous ne spécifiez pas de branche, le workflow se déclenche lorsque des modifications sont poussées vers la branche par défaut du référentiel.

Un workflow peut surveiller les poussées vers plusieurs référentiels ou branches.

on:
  push:
    - repo: your-org/your-product
    - repo: your-org/another-repo
      branch: release

​

Référentiels de contexte

Utilisez context pour accorder à l’agent un accès en lecture à des référentiels supplémentaires lors de l’exécution du workflow. Cela est utile lorsque votre prompt doit examiner du code ou du contenu en dehors de votre référentiel de documentation.

context:
  - repo: your-org/your-product
  - repo: your-org/design-system

​

Fusion automatique des modifications

Par défaut, l’agent ouvre une pull request (demande de fusion) pour chaque exécution de workflow afin que vous puissiez examiner les modifications avant leur mise en production. Activez automerge: true pour pousser les modifications directement vers votre branche de déploiement sans pull request.

automerge: true

​

Prompts

Des prompts efficaces se concentrent sur une seule tâche et visent un résultat précis. Les workflows présentent toujours une certaine variabilité en raison de la nature non déterministe des agents, mais vous pouvez améliorer la cohérence des résultats des workflows en suivant ces bonnes pratiques.

• Décrivez le résultat que vous souhaitez que l’agent produise.
• Incluez des critères de réussite.
• Précisez le contexte que vous voulez que l’agent utilise.
• Divisez les tâches complexes en étapes ou en plusieurs workflows.

​

Exemples de workflows

​

Brouillon de documentation pour les nouvelles fonctionnalités

Si vous utilisez les suggestions de l’agent dans votre Dashboard, ce workflow reproduit ce comportement.

Ajoutez ce workflow, en l’adaptant à votre projet, pour générer automatiquement des brouillons de documentation à mesure que vous ajoutez de nouvelles fonctionnalités à votre produit.

S’exécute lorsque des modifications sont poussées vers votre référentiel produit afin d’identifier les mises à jour de la documentation nécessaires pour toute nouvelle fonctionnalité ou API introduite.

.mintlify/workflows/draft-feature-docs.md

---
name: Draft docs for new features
on:
  push:
    - repo: your-org/your-product
      branch: main
context:
  - repo: your-org/your-docs
automerge: false
---

Review the diff from the last merged PR in `your-org/your-product`. Identify any new features, APIs, or other changes that require documentation.

For each new addition, draft documentation updates that explain what it does, when to use it, and how to configure it. Include a code example where relevant.

Success criteria: After reading any new or updated documentation, users understand what the feature is, if it applies to tasks they do, and how to use it.

## Important

- Only document changes that affect end users. Skip internal refactors or dependency updates.
- Match the style and structure of existing docs pages.

​

Audit de style

S’exécute lorsque des modifications sont poussées vers le référentiel de documentation, afin de détecter les écarts par rapport au guide de style avant qu’ils ne s’accumulent. Cet exemple de flux de travail corrige automatiquement ces écarts et répertorie dans le corps de la pull request toutes les violations qui nécessitent un jugement humain.

.mintlify/workflows/style-audit.md

---
name: Style audit
on:
  push:
    - repo: your-org/your-docs
      branch: main
automerge: false
---

Examinez tous les fichiers MDX modifiés dans le dernier PR fusionné par rapport au guide de style à `path/to/style-guide`.

Ouvrez une pull request pour résoudre les violations de style pouvant être corrigées automatiquement. Pour toute modification nécessitant un jugement ou de la nuance, notez-les dans le corps de la PR avec les lignes spécifiques, les violations de règles et les corrections suggérées.

Critères de succès :
- Toutes les violations de style ont une résolution proposée.
- Aucune nouvelle violation de style n'est introduite.

## Important

- Ne modifiez pas le sens du contenu. Corrigez uniquement les violations de style.
- Ignorez les fichiers dans les sous-répertoires de langue (`es/`, `fr/`, `zh/`).

​

Mettre à jour la référence d’API

Ce workflow s’exécute lorsque des modifications sont poussées vers le référentiel de votre produit afin de maintenir les pages de référence d’API synchronisées avec le code de votre produit. Lorsque des points de terminaison (endpoints) ou des paramètres sont modifiés, ce workflow met à jour le contenu correspondant dans votre documentation.

.mintlify/workflows/update-api-reference.md

---
name: Update API reference
on:
  push:
    - repo: your-org/your-product
      branch: main
context:
  - repo: your-org/your-docs
automerge: false
---

Review the diff from the last merged PR in `your-org/your-product` for changes to API endpoints, parameters, response shapes, or error codes.

Update the corresponding API specifications or pages in the docs to reflect the changes. Include updated parameter descriptions, type information, and examples where affected.

Success criteria: All API specifications and pages are up to date with the changes in the product repository.

## Important

- If a parameter or endpoint was removed, mark it as deprecated rather than deleting it unless the code explicitly removes it with no deprecation period.
- If no API changes were introduced, do nothing.

​

Suivre le retard de traduction

Exécutez ce workflow chaque semaine pour comparer les fichiers sources anglais à leurs traductions et repérer les pages qui ont pris du retard.

Pour utiliser ce workflow, mettez à jour les sous-répertoires de langue d’exemple (es/, fr/, zh/) avec vos sous-répertoires de langue réels.

.mintlify/workflows/translation-lag.md

---
name: Track translation lag
on:
  cron: "0 9 * * 3"
---

Compare the English MDX files in the repo against their counterparts in the `es/`, `fr/`, and `zh/` subdirectories. Use git history to identify English files updated more recently than their translations.

Open a pull request that lists pages that are out of sync, organized by language. For each page, include the date of the last English update and a brief summary of what changed so translators have context on what to update.

Success criteria: Any discrepancies between the English and translated files are identified and listed in the pull request.

## Important

- If a translated file does not exist, flag it as missing rather than out of sync.
- Group findings by language, then by how far out of date they are (most stale first).

​

Audit SEO et métadonnées

S’exécute chaque semaine pour rechercher les pages dont les métadonnées sont manquantes ou peu pertinentes, puis ouvrir une pull request (demande de fusion) avec des améliorations. Cet exemple de workflow vérifie l’absence du frontmatter description. Modifiez le workflow pour vérifier d’autres métadonnées ou problèmes de contenu que vous jugez prioritaires pour votre documentation.

.mintlify/workflows/seo-audit.md

---
name: SEO and metadata audit
on:
  cron: "0 9 * * 1"
automerge: false
---

Audit all MDX files in the docs for SEO and metadata quality. Check for:

- Missing or empty `description` frontmatter
- Descriptions that are too short (under 50 characters) or too long (over 160 characters)

Open a pull request with improvements for any issues found. Write descriptions that accurately summarize the page content in plain language.

Success criteria: All pages have up to date descriptions that accurately summarize the page content in plain language.

## Important

- Only update frontmatter. Do not change page content.
- If all pages have complete and reasonable metadata, do nothing.