mintlify__docs/fr/guides/automate-agent.mdx

---
title: "Automatiser la documentation quand le code change"
sidebarTitle: "Automatiser les mises à jour de la documentation"
description: "Configurez des mises à jour de documentation automatisées déclenchées par des changements de code en utilisant l'API de l'agent Mintlify avec des exemples GitHub Actions ou n8n."
keywords: ["automatisation avec agent", "n8n", "GitHub Actions", "mises à jour automatiques de la documentation"]
---

<div id="what-you-will-build">
  ## Ce que vous allez construire
</div>

Une automatisation qui met à jour votre documentation lorsque vous poussez du code sur votre branche principale. Vous pouvez créer ce workflow 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.

<div id="workflow-overview">
  ### Vue d’ensemble du workflow
</div>

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.

<div id="choose-your-platform">
  ## Choisissez votre plate-forme
</div>

<Tabs>
  <Tab title="GitHub Actions">
    GitHub Actions est l&#39;option la plus simple si votre code est déjà sur GitHub. Aucun service supplémentaire n&#39;est requis.

    ## Prérequis GitHub Actions

    * GitHub Actions activées sur vos dépôts de code et de documentation
    * [L&#39;application GitHub Mintlify](/fr/deploy/github) installée à la fois sur vos dépôts de code et de documentation
    * [Clé d’API administrateur Mintlify](https://dashboard.mintlify.com/settings/organization/api-keys)
    * [ID de projet Mintlify](https://dashboard.mintlify.com/settings/organization/api-keys)
    * [Forfait Mintlify Enterprise](https://mintlify.com/pricing)
    * Droits d’administrateur sur les dépôts GitHub de votre code et de votre documentation

    ### Installez l&#39;application Mintlify sur votre référentiel de code

    Installez l&#39;application Mintlify sur votre référentiel de code pour que l&#39;agent puisse récupérer le contexte depuis votre base de code. Pour ajouter l&#39;application à de nouveaux référentiels :

    1. Accédez à la page [Agent](https://dashboard.mintlify.com/products/agent) de votre Dashboard.
    1. Cliquez sur **Add to New Organization**. Vous accéderez à la page d'installation de l'application sur GitHub.
    1. Sélectionnez dans la liste les dépôts auxquels vous souhaitez accorder l'accès.
    1. Enregistrez vos modifications.

    ### Obtenez votre clé API d'administration

    1. Accédez à la page [Clés API](https://dashboard.mintlify.com/settings/organization/api-keys) 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 GitHub Actions

    ### 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 :

       ```yaml
       name: Update Docs

       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('Missing MINTLIFY_PROJECT_ID or MINTLIFY_API_KEY secrets');
                     return;
                   }

                   const url = `https://api.mintlify.com/v1/agent/${projectId}/job`;
                   const payload = {
                     branch: `mintlify/docs-update-${Date.now()}`,
                     messages: [
                       {
                         role: 'system',
                         content: 'You are an action runner that updates documentation based on code changes. You should never ask questions. If you are not able to access the repository, report the error and exit.'
                       },
                       {
                         role: 'user',
                         content: `Update the documentation for our recent pushes to main:\n\nRepository: ${owner}/${repo}`
                       }
                     ],
                     asDraft: false
                   };

                   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(`API request failed with status ${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(`Documentation update job triggered for ${owner}/${repo}`);
                   } catch (error) {
                     core.setFailed(`Failed to create documentation update job: ${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 administrateur Mintlify
       * Nom : `MINTLIFY_PROJECT_ID`, Secret : votre ID de projet Mintlify (disponible sur la page [Clés API](https://dashboard.mintlify.com/settings/organization/api-keys) de votre tableau de bord)

    Pour plus d&#39;informations, consultez [Utiliser les secrets dans GitHub Actions](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets) dans la documentation GitHub.

    ## Tester l&#39;automatisation GitHub Actions

    1. Apportez une légère modification à votre référentiel de code, puis poussez-la sur la branche main :
       ```bash
       git add .
       git commit -m "Test: trigger docs automation"
       git push origin main
       ```

    2. Consultez l’onglet **Actions** de votre dépôt de code pour vérifier que le workflow s’exécute.

    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 (demande de fusion) contenant les mises à jour de la documentation.

    ## Dépannage GitHub Actions

    ### Le workflow ne s&#39;exécute pas

    * Vérifiez que vous avez activé GitHub Actions dans votre référentiel de code.
    * Consultez l’onglet **Actions** pour vérifier la présence de messages d’erreur.
    * Assurez-vous que le fichier de workflow se trouve dans `.github/workflows/` et qu’il porte l’extension `.yml`.

    ### Erreur 401 de l&#39;API de l&#39;agent

    * Vérifiez que votre clé d’API commence par `mint_`.
    * Vérifiez que l’en-tête `Authorization` utilise le format `Bearer mint_yourkey`.
    * Confirmez que la clé d’API est associée à la bonne organisation Mintlify.

    ### Les mises à jour de la documentation n&#39;apparaissent pas

    * Vérifiez que vous avez connecté le dépôt de documentation à votre projet Mintlify.
    * Vérifiez que l’agent dispose des droits d’écriture sur le référentiel de documentation.
    * Consultez les journaux du workflow pour vérifier s’il y a des messages d’erreur de l’agent.
  </Tab>

  <Tab title="n8n">
    n8n fournit un éditeur de workflow visuel et peut s&#39;intégrer à plusieurs services.

    ## Prérequis n8n

    * Espace de travail n8n
    * [Forfait Mintlify Enterprise](https://mintlify.com/pricing)
    * Application Mintlify installée sur votre référentiel de code
    * Clé d’API administrateur Mintlify
    * Droits d’administrateur sur les dépôts GitHub de votre code et de votre documentation
    * Jeton d’accès personnel GitHub

    ### Installez l&#39;application Mintlify sur votre référentiel de code

    Installez l&#39;application Mintlify sur votre référentiel de code pour que l&#39;agent puisse récupérer le contexte depuis votre base de code. Pour ajouter l&#39;application à de nouveaux référentiels :

    1. Accédez à la page [Agent](https://dashboard.mintlify.com/products/agent) de votre Dashboard.
    1. Cliquez sur **Add to New Organization**. Vous accéderez à la page d'installation de l'application sur GitHub.
    1. Sélectionnez, dans la liste, les dépôts auxquels vous souhaitez accorder l'accès.
    1. Enregistrez vos modifications.

    ### Obtenez votre clé API d&#39;administration

    1. Accédez à la page [Clés API](https://dashboard.mintlify.com/settings/organization/api-keys) dans votre tableau de bord.
    2. Sélectionnez **Créer une clé API administrateur**.
    3. Copiez la clé et conservez-la en lieu sûr.

    ### Obtenez votre jeton d&#39;accès personnel GitHub

    1. Sur GitHub, accédez à **Paramètres**.
    2. Cliquez sur **Paramètres développeur**.
    3. Cliquez sur **Personal access tokens**.
    4. Cliquez sur **Tokens (classic)**.
    5. Cliquez sur **Generate new token (classic)**.
    6. Sélectionnez les autorisations suivantes :
       * `repo` (contrôle total des dépôts privés)
       * `admin:repo_hook` (si vous souhaitez que n8n crée des webhooks)
    7. Générez le jeton et stockez-le en lieu sûr.

    Pour plus d&#39;informations, consultez [Création d&#39;un jeton d&#39;accès personnel (classique)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens?versionId=free-pro-team%40latest\&productId=account-and-profile#creating-a-personal-access-token-classic) dans la documentation GitHub.

    ## Construire le workflow n8n

    ### Créer le déclencheur de webhook

    1. Dans n8n, créez un nouveau workflow.
    2. Ajoutez un nœud Webhook.
    3. Configurez le webhook :
       * Méthode HTTP : `POST`
       * Chemin : `auto-update-documentation` (ou n’importe quel chemin unique)
       * Authentification : aucune
       * Réponse : immédiate
    4. Enregistrez le workflow.
    5. Copiez l’URL du webhook de production. Son format est le suivant : `https://your-n8n-instance.app.n8n.cloud/webhook/auto-update-documentation`

    <Frame>
      <img
        src="/images/guides/n8n/webhook-node.png"
        alt="Capture d’écran des paramètres du nœud webhook."
        style={{
width: 'auto',
height: '700px',
}}
      />
    </Frame>

    ### Configurer le webhook GitHub

    1. Accédez à votre référentiel de code sur GitHub.
    2. Cliquez sur **Paramètres**.
    3. Cliquez sur **Webhooks**.
    4. Cliquez sur **Ajouter un webhook**.
    5. Configurez le webhook :
       * URL de la charge utile : collez l’URL de votre webhook n8n
       * Type de contenu : `application/json`
       * Quels événements doivent déclencher ce webhook ?
         * Sélectionnez **Let me select individual events.**
         * Sélectionnez uniquement **Push events**.
       * Sélectionnez **Active**
    6. Cliquez sur **Ajouter un webhook**.

    ### Filtrer les pushs vers la branche principale

    Ajoutez un nœud de code après le webhook pour filtrer les pushs vers main et extraire les informations pertinentes.

    1. Ajoutez un nœud de code.
    2. Nommez-le &quot;Filtrer les pushs vers main&quot;.
    3. Réglez le mode sur **Exécuter une seule fois pour tous les éléments**.
    4. Ajoutez ce code JavaScript :

    ```javascript
    const webhookData = $input.first().json.body;

    // Continuer uniquement s'il s'agit d'un push vers main
    if (webhookData.ref !== "refs/heads/main") {
      return [];
    }

    // Extraire les informations
    const repository = webhookData.repository;
    const pusher = webhookData.pusher;

    // Construire le message pour l'agent
    const agentMessage = `Mettre à jour la documentation pour les modifications poussées vers main dans ${repository.name}. Toujours modifier les fichiers et créer une pull request.`;

    return {
      json: {
        codeRepoName: repository.full_name,
        codeRepoShortName: repository.name,
        agentMessage: agentMessage
      }
    };
    ```

    <Frame>
      <img src="/images/guides/n8n/filter-merged-PRs-node.png" alt="Capture d’écran des paramètres du nœud « Filtrer les pushs vers main »." />
    </Frame>

    Ce code arrête le workflow si le push n&#39;a pas été effectué sur main, extrait toutes les informations pertinentes du webhook GitHub et crée un message pour l&#39;API de l&#39;agent.

    ### Appeler l&#39;API de l&#39;agent

    Ajoutez un nœud de requête HTTP pour créer un job de documentation.

    1. Ajoutez un nœud de requête HTTP.
    2. Appelez-le &quot;Create agent job.&quot;
    3. Configurez la requête :

       * Méthode : `POST`
       * URL : `https://api.mintlify.com/v1/agent/YOUR_PROJECT_ID/job` (remplacez `YOUR_PROJECT_ID` par l’ID de votre projet à partir de la page [API keys](https://dashboard.mintlify.com/settings/organization/api-keys))
       * Authentification : Generic Credential Type → Header Auth
         * Créez un nouveau justificatif d’authentification :
           * Name: `Authorization`
           * Value: `Bearer mint_YOUR_API_KEY` (remplacez par votre clé API)
       * Send Body: On
       * Body Content Type: JSON
       * Specify Body: Using JSON
       * Ajoutez ce JSON :

       ```json
       {
       "branch": "docs-update-from-{{ $json.codeRepoShortName }}-{{ $now.toISOString() }}",
       "messages": [
           {
           "role": "system",
           "content": "{{ $json.agentMessage }}"
           }
       ],
       "asDraft": false
       }
       ```

    <Frame>
      <img
        src="/images/guides/n8n/create-agent-job-node.png"
        alt="Capture d’écran des paramètres du nœud « Create Agent Job »."
        style={{
width: 'auto',
height: '700px',
}}
      />
    </Frame>

    L&#39;agent crée une pull request (demande de fusion) dans votre référentiel de documentation en utilisant un nom de branche descriptif qui inclut le nom du référentiel source et l&#39;horodatage.

    ### Activer le workflow

    1. Enregistrez votre workflow.
    2. Activez-le.

    Votre workflow surveille désormais votre référentiel de code pour détecter les pushs vers main.

    <Frame>
      <img src="/images/guides/n8n/workflow.png" alt="Capture d’écran du workflow d’automatisation dans l’éditeur n8n." />
    </Frame>

    ## Tester l&#39;automatisation n8n

    1. Créez une branche de test dans votre référentiel de code :
       ```bash
       git checkout -b test-docs-automation
       ```

    2. Apportez une petite modification et faites un commit :
       ```bash
       git add .
       git commit -m "Test: trigger docs automation"
       git push origin test-docs-automation
       ```

    3. Ouvrez une pull request (demande de fusion) sur GitHub.

    4. Fusionnez la pull request (demande de fusion).

    ### Vérifier l&#39;automatisation

    Vous devriez voir une nouvelle exécution n8n avec tous les nœuds terminés avec succès, ainsi qu&#39;une nouvelle branche et une pull request (demande de fusion) dans votre référentiel de documentation.

    ## Dépannage n8n

    ### Le webhook ne se déclenche pas

    * Vérifiez que le workflow est actif dans n8n.
    * Pour connaître le code de réponse, consultez Settings → Webhooks → Recent Deliveries dans les paramètres de votre dépôt GitHub.
    * Vérifiez que l’URL du webhook correspond exactement à l’URL de votre webhook n8n.

    ### Erreur 401 de l&#39;API de l&#39;agent

    * Vérifiez que votre clé d’API commence par `mint_`.
    * Vérifiez que l’en-tête `Authorization` utilise le format `Bearer mint_yourkey`.
    * Confirmez que la clé d’API est associée à la bonne organisation Mintlify.

    ### Erreur 401 de GitHub

    * Vérifiez que votre jeton dispose du scope `repo`.
    * Vérifiez que le jeton n&#39;a pas expiré.
    * Vérifiez que vous avez bien inclus l’en-tête `User-Agent` dans la requête GitHub.
  </Tab>
</Tabs>