branch. Les outils qui modifient le contenu, comme edit_page, create_node, update_config, publish et discard, l’exigent. Les outils de lecture, comme read, search, read_page_history, list_nodes, status et diff, utilisent votre branche de déploiement par défaut lorsque vous l’omettez. L’Admin MCP ne mémorise pas de branche d’un appel à l’autre, donc l’outil d’IA passe branch à chaque fois. Les requêtes portant sur des pages privées n’ont pas besoin de branch. L’Admin MCP ne peut accéder aux pages privées que dans les bases de connaissances. Dans les sites, les requêtes sur des pages privées renvoient private_pages_unavailable.
Le déroulement est le suivant :
1
Découvrir les projets (facultatif)
Si votre connexion a accès à plusieurs projets, appelez
list_deployments pour voir quelles valeurs de subdomain vous pouvez utiliser. Ignorez cette étape si votre connexion ne couvre qu’un seul projet.2
Lire, rechercher et modifier
L’IA utilise des outils comme
search, read, list_nodes, edit_page, write_page, create_node et update_config pour apporter des modifications. Sur une connexion à l’échelle de l’organisation, passez subdomain pour choisir le projet.Passez votre branche de déploiement comme branch pour la modifier directement. Les modifications arrivent sous forme de modifications non publiées. Consultez Modifier directement la branche de déploiement. Si votre projet exige une pull request, Mintlify refuse la modification avec un message qui en explique la raison et ne change rien. Appelez plutôt create_branch et passez le branchName renvoyé comme branch. Consultez Travailler sur une branche.3
Examiner le diff
Appelez
diff à tout moment pour voir exactement ce qui a changé sur une branche par rapport à votre branche de déploiement. Appelez status pour obtenir un résumé des fichiers modifiés, des clés docs.json modifiées et des modifications de navigation. Les deux portent sur votre branche de déploiement lorsque vous omettez branch. Ouvrez un editorUrl dans votre tableau de bord pour voir les mêmes modifications rendues. Lorsque create_node ajoute une page, il renvoie un editorUrl qui ouvre directement cette page.4
Publier
Appelez
publish avec la branch et un title pour publier vos modifications. L’Admin MCP indique à l’outil d’IA d’appeler publish uniquement lorsque vous lui demandez de publier, livrer ou fusionner : vos modifications restent donc non publiées jusque-là. Sur votre branche de déploiement, publish commite vos propres modifications en attente. Sur une branche, publish commite tout ce qui est en attente et renvoie la pull request de la branche, en en ouvrant une s’il n’y en a pas. Un nouvel appel sans rien de nouveau à commiter renvoie la pull request existante. S’il n’y a rien à commiter et aucune pull request, publish renvoie no_pending_changes.publish ne fusionne pas la pull request, sauf si vous passez merge: true. Avec merge: true, publish fusionne aussi la pull request dans votre branche de déploiement et renvoie merged: true. Mintlify n’autorise la fusion que s’il accepterait des modifications directes sur votre branche de déploiement. Consultez Modifier directement la branche de déploiement. Sinon, publish renvoie merge_not_allowed avec la raison et laisse la pull request ouverte pour relecture. Demandez à l’outil d’IA de fusionner uniquement lorsque vous voulez que les modifications contournent la relecture.La réponse inclut un editorUrl qui ouvre la première page créée ou mise à jour. Si les modifications ne concernent que la configuration, le lien ouvre la branche. Les anciens clients peuvent toujours passer mode, mais publish l’ignore.5
Vérifier le déploiement
Lorsque
publish commite sur votre branche de déploiement, directement ou en fusionnant la pull request, la réponse inclut un commitSha et un objet deployment. Vos modifications ne sont pas en ligne sur votre site tant que le déploiement n’est pas terminé. Appelez deployment_status avec le commitSha pour suivre la progression. L’outil d’IA vérifie à nouveau environ toutes les 30 secondes jusqu’à ce que live vaille true, ou s’arrête et rapporte le message si l’état est failed, not_live ou skipped.6
Abandonner si nécessaire
Appelez
discard avec la branch pour abandonner vos modifications. Ce qu’il supprime dépend de la branche. Consultez Modifier directement la branche de déploiement et Travailler sur une branche.branch et l’Admin MCP la modifie comme vous le faites dans l’éditeur du tableau de bord. Vous n’appelez pas create_branch et aucune pull request n’est créée.
L’outil d’IA agit en votre nom sur la branche de déploiement :
- Les modifications sont visibles en direct par les collaborateurs. Toute autre personne qui modifie la branche de déploiement dans le tableau de bord voit les modifications de l’IA au fur et à mesure.
publishpublie uniquement vos modifications. Il commite vos modifications en attente directement sur la branche de déploiement, comme un clic sur Publish dans l’éditeur. Les modifications non publiées des autres restent en attente. Vos propres modifications non publiées dans l’éditeur du tableau de bord sont également publiées.discardannule uniquement vos modifications. Il renvoiediscardedChangesavec le nombre de modifications annulées. Les modifications des autres et la branche elle-même restent intactes.statusliste uniquement vos modifications.
list_deployments renvoie projectType: "workspace", le projet est une base de connaissances, et Mintlify valide automatiquement les modifications sur la branche de déploiement, y compris les images téléversées.
Mintlify suit les modifications par page. Si vous et une autre personne avez modifié la même page, publish publie la page entière et discard annule la page entière, y compris les modifications de l’autre personne.
Mintlify refuse les modifications sur la branche de déploiement, et ne change rien, dans l’un des cas suivants :
- Pousser directement sur votre branche de déploiement est désactivé dans vos paramètres de publication.
- La protection de votre branche de déploiement exige des pull requests, ou Mintlify ne peut pas vérifier vos règles de protection de branche.
- La modification de la branche de déploiement est verrouillée dans l’éditeur du tableau de bord.
- Vous vous êtes connecté avec un jeton client ou machine à machine au lieu d’une connexion OAuth. Ces jetons ne sont pas liés à un utilisateur et n’ont donc pas de modifications « propres ».
publish renvoie branch_protected et vos modifications restent en attente. Ouvrez l’éditeur du tableau de bord pour les déplacer vers une nouvelle branche. Il en va de même si Always require branches est activé et que vous n’êtes pas administrateur.
Si la publication automatique est activée pour votre projet, l’Admin MCP n’utilise pas de branches pour celui-ci. Passez votre branche de déploiement comme branch. Mintlify commite automatiquement vos modifications sur la branche de déploiement.
Mintlify refuse create_branch et les appels sur toute autre branche dans ces projets, et ne change rien. Si votre connexion ne couvre que ce projet, l’Admin MCP ne liste ni create_branch ni list_branches.
Pousser directement sur votre branche de déploiement et la protection de branche ne bloquent pas les modifications de la branche de déploiement dans un projet avec publication automatique. Mintlify refuse les modifications lorsque la modification de la branche de déploiement est verrouillée dans l’éditeur du tableau de bord ou lorsque vous vous êtes connecté avec un jeton client ou machine à machine.
Si votre projet exige une relecture avant publication, seuls les administrateurs peuvent utiliser publish sur votre branche de déploiement. Pour toute autre personne, publish sur la branche de déploiement renvoie review_required et les modifications restent en attente.
Sur les autres branches, publish commite vos modifications et ouvre une pull request. Les administrateurs peuvent fusionner des pull requests dans la branche de déploiement avec merge: true. Les publieurs peuvent fusionner une fois que les relecteurs ont approuvé toutes les modifications de la branche, y compris ses Site changes. Pour toute autre personne, une fusion renvoie review_required et la pull request reste ouverte : demandez plutôt une relecture sur la branche.
Pour faire publier vos modifications, demandez à l’outil d’IA de demander une relecture. L’outil d’IA appelle request_review avec les pages que vous avez modifiées et les relecteurs que vous nommez. Une fois qu’un relecteur a approuvé les modifications, un administrateur ou un publieur les publie depuis l’éditeur du tableau de bord ou avec publish_review_request. Consultez Demandes de relecture pour les outils.
Appelez create_branch avec un title lorsque votre projet exige une pull request, ou lorsque vous en voulez une malgré tout. Mintlify crée une nouvelle branche à partir de votre branche de déploiement, la nomme <your-name>/<title-slug> comme l’éditeur du tableau de bord nomme les branches, et l’initialise à partir de votre contenu publié. La pull request s’ouvre avec ce titre. Par exemple, create_branch { subdomain: "acme", title: "Add tips page" }.
Pour partir d’une autre branche existante, comme une branche de fonctionnalité pour une mise à jour importante, passez son nom comme from. Par exemple, create_branch { subdomain: "acme", title: "Add tips page", from: "docs-refresh" }. Mintlify refuse les branches from qui n’existent pas et ne crée rien.
Si votre dépôt est hébergé sur GitHub, GitLab ou Azure Repos, une branche que vous créez à partir d’une branche autre que votre branche de déploiement devient une sous-branch, et sa pull request cible la branche from au lieu de votre branche de déploiement.
create_branch renvoie le branchName, la baseBranch et le baseSha de départ, une note et un editorUrl que vous pouvez ouvrir pour suivre l’avancement dans l’éditeur du tableau de bord. Passez le branchName comme branch dans tous les appels suivants.
Pour travailler sur une branche existante, passez son nom comme branch. Appelez list_branches pour découvrir les branches du dépôt d’un projet. Mintlify refuse les appels sur des branches qui n’existent pas.
Sur une branche, Mintlify commite automatiquement vos modifications, environ 15 secondes après la dernière modification. Cela inclut le contenu des pages, les modifications de navigation et les mises à jour de docs.json. Le premier commit ouvre une pull request vers votre branche de déploiement, ou vers la branche from pour une sous-branch. La pull request s’ouvre en brouillon si Create draft pull requests by default est activé. Rien n’atteint votre branche de déploiement tant que quelqu’un n’y a pas fusionné les modifications.
discard sur une branche autre que votre branche de déploiement supprime la branche et ferme sa pull request, même si la branche contient des commits. Cela équivaut à supprimer une branche dans l’éditeur du tableau de bord. discard ne supprime que les branches que vous avez créées dans Mintlify. Pour toute autre branche, il refuse et ne change rien.
La section Publication de la page MCP → Configure dans la barre latérale de votre tableau de bord contrôle si l’Admin MCP peut modifier votre branche de déploiement sans pull request. Activez Pousser directement sur votre branche de déploiement pour permettre aux outils d’IA de modifier et de publier directement sur votre branche de déploiement. Désactivez-la pour exiger create_branch et une pull request pour les modifications MCP.
Ce bouton partage le même paramètre agentReviewProcess que l’agent Slack et l’agent du tableau de bord, donc toute modification ici s’applique également à ces flux.
Le bouton est désactivé dans trois cas :
- Votre branche de déploiement requiert une pull request. Si des règles de protection de branche ou des approbations requises empêchent les push directs, les modifications MCP passent toujours par une pull request, quel que soit ce paramètre.
- Mintlify héberge votre projet. Pour les sites hébergés par Mintlify, les modifications MCP sont toujours poussées directement, sauf si la protection de branche exige tout de même une pull request.
- Vous n’êtes pas administrateur. La modification de ce paramètre requiert le rôle d’administrateur sur votre projet. Les éditeurs et les lecteurs voient le bouton désactivé avec une bannière de permission.