Tutoriel : Mettre à jour automatiquement la documentation lorsque le code change

Utilisez l’API de l’agent pour mettre à jour automatiquement votre documentation.

​

Ce que vous allez construire

Une automatisation qui met à jour votre documentation lorsqu’un code est poussé sur votre branche principale. Le workflow peut être créé sur plusieurs plateformes, notamment GitHub Actions et n8n. Il surveille votre référentiel de code, puis appelle l’API de l’agent pour mettre à jour votre documentation dans un référentiel de documentation distinct.

Ce workflow relie deux référentiels distincts :

• Référentiel de code : l’endroit où vous stockez le code de l’application. Vous y configurerez le déclencheur d’automatisation. Exemples : une API backend, une application frontend, un SDK ou un outil CLI.
• Référentiel de documentation : l’endroit où vous stockez votre documentation et que vous connectez à votre projet Mintlify. L’agent crée des pull requests (demandes de fusion) contenant des mises à jour de la documentation dans ce référentiel.

Ce tutoriel part du principe que votre documentation se trouve dans un référentiel distinct de votre code applicatif. Si vous utilisez un monorepo, modifiez le workflow pour cibler le répertoire où vous stockez votre documentation.

​

Vue d’ensemble du workflow

1. Quelqu’un pousse du code sur votre branche principale.
2. Le workflow se déclenche.
3. Le workflow appelle l’API de l’agent pour mettre à jour votre documentation.
4. L’agent crée une pull request (demande de fusion) contenant les mises à jour de la documentation dans votre référentiel de documentation.

​

Choisissez votre plate-forme

GitHub Actions

GitHub Actions est l’option la plus simple si votre code est déjà sur GitHub. Aucun service supplémentaire n’est requis.

​

Prérequis

• GitHub Actions activées sur vos dépôts de code et de documentation
• L’application GitHub Mintlify installée à la fois dans vos dépôts de code et de documentation
• Clé d’API Admin Mintlify
• ID de projet Mintlify
• Forfait Mintlify Pro ou Custom
• Accès administrateur aux dépôts GitHub de votre code et de votre documentation

​

Installez l’application Mintlify sur votre dépôt de code

L’application Mintlify doit être installée sur votre dépôt de code pour que l’agent puisse récupérer le contexte depuis votre base de code. Pour ajouter l’application à de nouveaux dépôts :

1. Accédez à la page Agent de votre tableau de bord Mintlify.
2. Cliquez sur Add to new organization. Vous serez redirigé vers la page d’installation de l’application sur GitHub.
3. Sélectionnez dans la liste les dépôts auxquels vous souhaitez accorder l’accès.
4. Enregistrez vos modifications.

​

Obtenez votre clé API d’administration

1. Accédez à la page Clés API depuis votre tableau de bord.
2. Sélectionnez Créer une clé API administrateur.
3. Copiez la clé et conservez-la en lieu sûr.

​

Construire le workflow

​

Créer le fichier de workflow

1. Dans votre dépôt de code, créez un nouveau fichier : .github/workflows/update-docs.yml

2. Ajoutez le workflow suivant :

   name: Mettre à jour la documentation
   
   on:
   push:
       branches:
       - main
   
   jobs:
   update-docs:
       runs-on: ubuntu-latest
       steps:
       - uses: actions/github-script@v8
           env:
           MINTLIFY_API_KEY: ${{ secrets.MINTLIFY_API_KEY }}
           PROJECT_ID: ${{ secrets.MINTLIFY_PROJECT_ID }}
           with:
           script: |
               const { owner, repo } = context.repo;
               const projectId = process.env.PROJECT_ID;
               const apiKey = process.env.MINTLIFY_API_KEY;
   
               if (!projectId || !apiKey) {
               core.setFailed('Secrets MINTLIFY_PROJECT_ID ou MINTLIFY_API_KEY manquants');
               return;
               }
   
               const url = `https://api.mintlify.com/v1/agent/${projectId}/job`;
               const payload = {
               branch: `mintlify/docs-update-${Date.now()}`,
               messages: [
                   {
                   role: 'system',
                   content: 'Vous êtes un exécuteur d'action qui met à jour la documentation en fonction des modifications du code. Vous ne devez jamais poser de questions. Si vous ne parvenez pas à accéder au dépôt, signalez l'erreur et quittez.'
                   },
                   {
                   role: 'user',
                   content: `Mettez à jour la documentation pour nos récents pushs vers main :\n\nDépôt : ${owner}/${repo}`
                   }
               ]
               };
   
               try {
                   const response = await fetch(url, {
                   method: 'POST',
                   headers: {
                       'Authorization': `Bearer ${apiKey}`,
                       'Content-Type': 'application/json'
                   },
                   body: JSON.stringify(payload)
                   });
   
                   if (!response.ok) {
                   throw new Error(`La requête API a échoué avec le statut ${response.status} : ${await response.text()}`);
                   }
   
                   const reader = response.body.getReader();
                   const decoder = new TextDecoder();
                   let buffer = '';
   
                   while (true) {
                   const { done, value } = await reader.read();
                   if (done) break;
                   buffer += decoder.decode(value, { stream: true });
                   const lines = buffer.split('\n');
                   buffer = lines.pop() || '';
                   for (const line of lines) {
                       if (line.trim()) {
                       console.log(line);
                       }
                   }
                   }
                   if (buffer.trim()) {
                   console.log(buffer);
                   }
   
                   core.notice(`Tâche de mise à jour de la documentation déclenchée pour ${owner}/${repo}`);
               } catch (error) {
                   core.setFailed(`Échec de la création de la tâche de mise à jour de la documentation : ${error.message}`);
               }
   

​

Ajouter des secrets

1. Dans votre dépôt de code, accédez à Settings → Secrets and variables → Actions.
2. Cliquez sur New repository secret.
3. Ajoutez les secrets suivants :
   • Nom : MINTLIFY_API_KEY, Secret : votre clé d’API d’administration Mintlify
   • Nom : MINTLIFY_PROJECT_ID, Secret : votre identifiant de projet Mintlify (disponible sur la page Clés d’API de votre tableau de bord)

Pour plus d’informations, consultez Utiliser les secrets dans GitHub Actions dans la documentation GitHub.

​

Tester l’automatisation

1. Effectuez une petite modification dans votre dépôt de code, puis poussez-la sur la branche main :

   git add .
   git commit -m "Test : déclencher l'automatisation des docs"
   git push origin main
   

2. Consultez l’onglet Actions dans votre dépôt de code pour voir le workflow en cours d’exécution.

3. Après l’exécution du workflow, vérifiez le dépôt de votre documentation pour y trouver une nouvelle branche et une pull request contenant les mises à jour de la documentation.

​

Dépannage

​

Le workflow ne s’exécute pas

• Vérifiez que GitHub Actions est activé dans votre dépôt.
• Consultez l’onglet Actions pour voir les messages d’erreur.
• Assurez-vous que le fichier de workflow se trouve dans .github/workflows/ et qu’il a l’extension .yml.

​

Erreur 401 de l’API de l’agent

• Vérifiez que votre clé API commence par mint_.
• Vérifiez que l’en-tête Authorization est au format Bearer mint_yourkey.
• Assurez-vous que la clé d’API correspond à la bonne organisation Mintlify.

​

Les mises à jour de la documentation n’apparaissent pas

• Vérifiez que le dépôt de documentation est bien connecté à votre projet Mintlify.
• Vérifiez que l’agent dispose des droits d’écriture sur le dépôt de documentation.
• Vérifiez les journaux du workflow pour repérer les messages d’erreur émis par l’agent.