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. Contactez-nous directement pour les activer.

Les workflows exécutent l’agent automatiquement selon un calendrier défini ou lorsqu’un push est effectué sur un référentiel que vous spécifiez. 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.

​

Créer un fichier de workflow

Créez des fichiers .md 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 de la fusion

Exécutez un workflow lorsqu’une pull request (demande de fusion) est fusionnée sur un référentiel et une branche spécifiques.

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 fusions. Si vous ne spécifiez pas de branche, le workflow se déclenche lorsqu’une fusion est effectuée vers la branche par défaut du référentiel.

Un workflow peut surveiller les fusions dans plusieurs référentiels ou branches.

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

​

Référentiels de référence

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

​

Audit de style

S’exécute lorsqu’une pull request (demande de fusion) de documentation est fusionnée, 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/`).

​

Brouillon de documentation pour les nouvelles fonctionnalités

S’exécute lorsque des pull requests (demandes de fusion) sont fusionnées dans 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.

​

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

Ce workflow s’exécute lorsque des pull requests (demandes de fusion) sont fusionnées dans 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.