> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.another-horizon.eu/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 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](/fr/deploy/github) installée à la fois dans vos dépôts de code et de documentation
* [Clé d’API Admin Mintlify](https://dashboard.mintlify.com/settings/organization/api-keys)
* [ID de projet Mintlify](https://dashboard.mintlify.com/settings/organization/api-keys)
* [Forfait Mintlify Pro ou Custom](https://mintlify.com/pricing)
* Droits d’administrateur sur les dépôts GitHub de votre code et de votre documentation
### Installez l'application Mintlify sur votre référentiel de code
L'application Mintlify doit être installée sur votre référentiel de code pour que l'agent puisse récupérer le contexte depuis votre base de code. Pour ajouter l'application à de nouveaux référentiels :
1. Ouvrez le panneau Agent dans votre tableau de bord Mintlify.
2. Cliquez sur le bouton **Paramètres**.
3. Cliquez sur **Add to New Organization**. Vous accéderez à la page d'installation de l'application sur GitHub.
4. Sélectionnez dans la liste les dépôts auxquels vous souhaitez accorder l’accès.
5. 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
### 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 theme={null}
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 référentiel, signalez l'erreur et quittez.'
},
{
role: 'user',
content: `Mettez à jour la documentation pour nos récents pushs vers main :\n\nRéférentiel : ${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(`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 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'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'automatisation
1. Apportez une petite modification à votre référentiel de code, puis poussez-la sur la branche main :
```bash theme={null}
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 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 référentiel de code.
* 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é d’API commence par `mint_`.
* Vérifiez que l’en-tête `Authorization` est bien au format `Bearer mint_yourkey`.
* Confirmez que la clé d’API est associée à 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 en écriture sur le référentiel de documentation.
* Vérifiez les journaux du workflow pour repérer les messages d’erreur émis par l’agent.
n8n fournit un éditeur de workflow visuel et peut s'intégrer à plusieurs services.
## Prérequis
* Espace de travail n8n
* [Forfait Mintlify Pro ou Custom](https://mintlify.com/pricing)
* Application Mintlify installée sur votre dépôt de code
* Clé d’API d’administration 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'application Mintlify sur votre référentiel de code
L'application Mintlify doit être installée sur votre référentiel de code pour que l'agent puisse récupérer le contexte depuis votre base de code. Pour ajouter l'application à de nouveaux référentiels :
1. Ouvrez le panneau Agent dans votre tableau de bord Mintlify.
2. Cliquez sur le bouton **Paramètres**.
3. Cliquez sur **Add to New Organization**. Vous serez redirigé vers la page d'installation de l'application sur GitHub.
4. Sélectionnez les dépôts auxquels vous souhaitez accorder l’accès dans la liste.
5. 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.
### Obtenez votre jeton d'accès personnel GitHub
1. Sur GitHub, accédez à **Paramètres**.
2. Cliquez sur **Paramètres du 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 conservez-le en lieu sûr.
Pour plus d'informations, consultez [Création d'un jeton d'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
### 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 votre workflow.
5. Copiez l’URL du webhook de production. Elle a la forme suivante : `https://your-n8n-instance.app.n8n.cloud/webhook/auto-update-documentation`
### Configurer le webhook GitHub
1. Accédez à votre référentiel de code sur GitHub.
2. Cliquez sur **Settings**.
3. Cliquez sur **Webhooks**.
4. Cliquez sur **Ajouter un webhook**.
5. Configurez le webhook :
* URL de charge utile : collez l’URL de votre webhook n8n
* Type de contenu : `application/json`
* Quels événements souhaitez-vous utiliser pour 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 « Filtrer les pushs vers main ».
3. Réglez le mode sur **Exécuter une seule fois pour tous les éléments**.
4. Ajoutez ce JavaScript :
```javascript theme={null}
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
}
};
```
Ce code arrête le workflow si le push n'a pas été effectué sur main, extrait toutes les informations pertinentes du webhook GitHub et crée un message pour l'API de l'agent.
### Appeler l'API de l'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. Nommez-le « Create agent job. »
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 theme={null}
{
"branch": "docs-update-from-{{ $json.codeRepoShortName }}-{{ $now.toISOString() }}",
"messages": [
{
"role": "system",
"content": "{{ $json.agentMessage }}"
}
],
"asDraft": false
}
```
L'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'horodatage.
### Activer le workflow
1. Enregistrez votre workflow.
2. Passez-le en mode actif.
Votre workflow surveille désormais votre référentiel de code pour détecter les pushs vers main.
## Tester l'automatisation
1. Créez une branche de test dans votre dépôt de code :
```bash theme={null}
git checkout -b test-docs-automation
```
2. Apportez une petite modification et faites un commit :
```bash theme={null}
git add .
git commit -m "Test : déclencher l'automatisation des docs"
git push origin test-docs-automation
```
3. Ouvrez une pull request sur GitHub.
4. Fusionnez la pull request.
### Vérifier l'automatisation
Vous devriez voir une nouvelle exécution n8n avec tous les nœuds terminés avec succès, ainsi qu'une nouvelle branche et une pull request (demande de fusion) dans votre référentiel de documentation.
## Dépannage
### 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.
* Confirmez que l’URL du webhook correspond exactement à celle de votre webhook n8n.
### Erreur 401 de l'API de l'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`.
* Assurez-vous que la clé d’API correspond à la bonne organisation Mintlify.
### Erreur 401 de GitHub
* Vérifiez que votre jeton inclut le scope `repo`.
* Vérifiez que le jeton n'a pas expiré.
* Vérifiez que vous avez bien inclus l’en-tête `User-Agent` dans la requête GitHub.