Intégration GitHub sur Mastra Platform

L’intégration GitHub relie un projet Mastra Platform à un dépôt GitHub. Lorsque vous envoyez des modifications vers votre dépôt, Studio et Server sont automatiquement déployés.

remarque

L’intégration fonctionne uniquement avec les dépôts hébergés sur GitHub.com. Les instances GitHub Enterprise auto-hébergées ne sont pas prises en charge pour le moment.

Une fois un dépôt lié, la plateforme :

• Compile et déploie Studio et Server à chaque push vers les branches configurées.
• Provisionne des bases de données gérées et la clé d’API Gateway pour les projets créés à partir d’un modèle.
• Affiche le contexte du commit, de la branche et de la pull request pour chaque déploiement.
• Renvoie l’état de la compilation à GitHub sous forme d’exécutions de vérification, et l’affiche dans le tableau de bord du projet avec des badges d’état en direct et des journaux intégrés.

Quand utiliser l’intégration GitHub

Choisissez l’intégration GitHub dans les cas suivants :

• Vous souhaitez déployer à chaque push depuis main ou toute autre branche, y compris avec des branches distinctes pour Studio et Server.
• Vous souhaitez un parcours d’intégration géré qui crée la structure d’un projet à partir d’un modèle Mastra, avec un nouveau dépôt, une base de données gérée et une clé d’API Gateway.
• Vous avez besoin du contexte des pull requests et des commits dans le tableau de bord de la plateforme pour faciliter l’analyse.

Le flux CLI (mastra studio deploy et mastra server deploy) reste disponible pour les déploiements ponctuels et les fournisseurs de CI autres que GitHub. Consultez Studio et Server pour suivre le parcours exclusivement fondé sur la CLI.

Installer l’application GitHub Mastra

L’intégration repose sur l’application GitHub Mastra.

L’application lit le contenu des dépôts et écoute les événements push sur les branches configurées. Elle renvoie l’état du déploiement sous forme d’exécutions de vérification.

1. Dans le tableau de bord Mastra Platform, ouvrez les paramètres de votre organisation. La page comprend une section Application GitHub.

2. Sélectionnez Installer l’application GitHub, puis choisissez le compte ou l’organisation GitHub où l’installer.

   Si vous ne possédez pas l’organisation GitHub, GitHub crée une demande d’installation en attente qu’un administrateur doit approuver. Le tableau de bord suit les demandes en attente avec les installations terminées.

3. Sélectionnez les dépôts auxquels l’application peut accéder. Vous pouvez limiter l’accès à certains dépôts ou l’accorder à tous les dépôts du compte.

   Vous pouvez révoquer ou modifier l’accès aux dépôts à tout moment depuis les paramètres de l’application sur GitHub.

remarque

Si GitHub modifie ultérieurement les autorisations requises par l’application, le tableau de bord affiche un avertissement Autorisations obsolètes accompagné d’un lien d’approbation. Les opérations sur les dépôts renvoient un code 403 jusqu’à ce qu’un administrateur approuve de nouveau les autorisations.

Demandes d’installation en attente

Lorsqu’une personne qui n’est pas administratrice demande l’installation de l’application dans une organisation, la demande reste en attente jusqu’à ce qu’un administrateur de l’organisation l’approuve sur GitHub.com. Le tableau de bord :

• Répertorie les demandes en attente à côté des installations actives.
• Permet au même utilisateur de demander simultanément l’accès à plusieurs comptes GitHub.
• Réconcilie l’état en attente avec GitHub à l’ouverture de la page, en supprimant les demandes qu’un administrateur a refusées ou que le demandeur a retirées.

Pour annuler une demande en attente, sélectionnez Annuler à côté de celle-ci dans le tableau de bord.

Créer un projet à partir d’un modèle

Les modèles sont le moyen le plus rapide de commencer. La plateforme crée un nouveau dépôt à partir d’un modèle Mastra, le relie à un nouveau projet, provisionne les bases de données gérées déclarées par le modèle et lance le premier déploiement.

1. Dans le tableau de bord, sélectionnez Créer un projet, puis Partir d’un modèle.

2. Choisissez un modèle et sélectionnez le compte GitHub propriétaire du nouveau dépôt. Nommez le dépôt et indiquez s’il doit être privé.

3. Configurez les besoins du modèle en bases de données gérées. Les modèles peuvent déclarer des bases de données requises, comme Turso ou Neon ; vous choisissez alors le fournisseur et la région pour chaque besoin.

4. Ajoutez les variables d’environnement propres au modèle, par exemple les clés d’API des fournisseurs d’IA. La plateforme initialise automatiquement MASTRA_GATEWAY_API_KEY et MASTRA_PLATFORM_ACCESS_TOKEN afin que le code du modèle qui communique avec Gateway fonctionne dès le premier déploiement.

5. Sélectionnez Créer un projet. La plateforme crée le dépôt, y écrit un fichier de configuration .mastra-project.json, provisionne les bases de données gérées et déclenche les premiers déploiements de Studio et Server.

Le déploiement initial attend la fin du provisionnement des bases de données gérées avant de démarrer. La première compilation du modèle dispose ainsi des variables d’environnement de connexion aux bases de données.

Lier un dépôt existant

Suivez ce parcours si vous disposez déjà d’un projet Mastra dans un dépôt GitHub.

1. Dans le tableau de bord, sélectionnez Créer un projet, puis Connecter un dépôt existant. Vous pouvez également ouvrir un projet existant et sélectionner Lier un dépôt dans ses paramètres.

2. Choisissez une installation, puis le dépôt. La recherche porte sur tous les dépôts auxquels l’application peut accéder dans cette installation.

3. Choisissez les branches de déploiement de Studio et de Server. Les deux cibles utilisent par défaut la branche par défaut du dépôt ; elles peuvent partager une branche ou utiliser des branches différentes.

   Vous pouvez désactiver Studio ou Server pour le projet. Le panneau manuel Déployer depuis GitHub sélectionne par défaut les deux cibles lorsqu’elles sont toutes deux configurées.

4. Sélectionnez Lier le dépôt. La plateforme vérifie que le dépôt ne contient pas déjà un fichier .mastra-project.json pointant vers un autre projet. Si c’est le cas, le tableau de bord vous avertit et propose une option Écraser qui remplace le fichier lors de la liaison.

Après la liaison, le push suivant vers la branche configurée déclenche un déploiement.

Conflits de .mastra-project.json

La plateforme écrit un fichier .mastra-project.json dans chaque dépôt lié afin d’identifier le projet. Lorsque vous liez un dépôt qui contient déjà un tel fichier, le tableau de bord vérifie son contenu avant l’envoi :

• Absent : la plateforme crée le fichier lors de la liaison.
• Correspondant : le fichier pointe déjà vers le projet que vous liez ; aucune modification n’est donc nécessaire.
• En conflit : le fichier pointe vers un autre projet. Vous pouvez annuler ou écraser explicitement le fichier.

Consultez la page Configuration pour connaître le schéma du fichier.

Déploiement à chaque push

Une fois le dépôt lié, chaque push vers une branche configurée déclenche un déploiement :

• Un push vers la branche Studio déclenche un déploiement de Studio.
• Un push vers la branche Server déclenche un déploiement de Server.
• Si les deux cibles partagent une branche, un seul push déclenche les deux déploiements en parallèle.

Chaque déploiement contient le SHA du commit, la branche et, lorsqu’il est disponible, le numéro de la pull request qui a introduit le commit. Les compilations s’exécutent sur la plateforme et renvoient leur état à GitHub sous forme d’exécutions de vérification sur le commit.

Une seule compilation par cible de déploiement s’exécute à la fois. Si un nouveau push arrive pendant une compilation, la plateforme annule les anciennes compilations en attente pour cette cible et exécute la plus récente. Les compilations de Studio et de Server sont suivies indépendamment ; elles peuvent donc s’exécuter en parallèle lorsque les deux cibles sont configurées.

Déploiements GitHub manuels

Vous pouvez également déclencher un déploiement depuis le tableau de bord sans effectuer de push. Ouvrez le projet, sélectionnez Déployer depuis GitHub, choisissez la cible (Studio, Server ou les deux) et une branche, puis validez. La plateforme exécute le déploiement sur le commit de tête de cette branche et enregistre le déclencheur comme un déploiement Workflow GitHub.

Suivre les déploiements

Après la création d’un projet à partir d’un modèle ou sa liaison à un dépôt, la page Configuration affiche une ligne par cible de déploiement. Chaque ligne :

• Affiche un badge d’état en direct qui interroge le déploiement jusqu’à sa fin.
• Renvoie vers la page de détails du déploiement à l’aide de son identifiant.
• Propose un bouton Afficher les journaux qui diffuse les journaux de compilation et d’exécution directement dans la page. Les journaux de Server sont interrogés toutes les trois secondes tant que le déploiement est actif.

Autorisations et révocation

Pour arrêter les déploiements depuis un dépôt, effectuez l’une des actions suivantes :

• Dissociez le dépôt du projet dans Paramètres du projet → Dépôt. Le projet conserve son historique et vous pourrez lier un autre dépôt ultérieurement.
• Supprimez l’accès au dépôt pour l’application GitHub Mastra sur GitHub.com. Les déploiements existants continuent de s’exécuter, mais aucun nouveau push ne déclenche de déploiement.
• Désinstallez l’application GitHub du compte GitHub. Cela supprime l’accès à tous les dépôts de ce compte.

Si GitHub révoque ou renouvelle le token d’installation de l’application, les lectures de dépôt renvoient une erreur github_app_permissions_outdated et le tableau de bord invite un administrateur à approuver de nouveau les autorisations.

Ressources associées

• Vue d’ensemble de Mastra Platform
• Studio sur Mastra Platform
• Server sur Mastra Platform
• Configuration