OrbitWake Code
Workflows Git
OrbitWake sépare aujourd’hui l’état privé d’un projet Code des opérations effectuées sur un dépôt GitHub autorisé. Cette page explique ce qui est réellement disponible : lecture du dépôt, branches, écritures qui créent des commits, pull requests et approbation des actions sensibles.
Code et Git ne sont pas le même historique
Un projet OrbitWake Code possède son propre état : fichiers de projet, builds AI, sauvegarde, checkpoints, preview et historique de travail. Cet état interne permet d’itérer rapidement sans transformer automatiquement chaque modification en commit Git.
GitHub représente un dépôt externe, avec ses branches, commits, issues et pull requests. Une modification visible dans Code n’est donc pas automatiquement poussée vers GitHub, et un checkpoint Code n’est pas un commit Git.
Cette séparation est volontaire : elle évite qu’un build AI réussi déclenche à lui seul une opération externe et permet de revoir le résultat avant d’écrire dans un dépôt partagé.
Autoriser GitHub avant toute opération
Les opérations GitHub disponibles dans OrbitWake passent par le connecteur GitHub. Le connecteur utilise une authentification GitHub et ne peut travailler que sur les dépôts accessibles par l’installation connectée et par l’utilisateur GitHub authentifié.
OrbitWake peut en plus restreindre les ressources autorisées à une liste de dépôts. Lorsqu’un dépôt se trouve hors de cette portée, l’action est refusée avant l’appel GitHub.
Cette portée s’applique autant aux lectures qu’aux écritures. Connecter GitHub ne signifie donc pas que tous les dépôts du compte deviennent automatiquement disponibles à toutes les actions.
Ce que le connecteur peut lire
La version actuelle du connecteur GitHub fournit plusieurs actions de lecture utilisables avant de modifier un dépôt.
| Action | Utilité |
|---|---|
| Liste des dépôts | Identifier les dépôts accessibles par l’installation GitHub connectée. |
| Recherche de code | Rechercher du code dans un dépôt explicitement autorisé. |
| Lecture de fichier | Lire un fichier UTF-8, éventuellement sur une branche, un tag ou un commit précis. |
| Liste des branches | Voir les branches existantes avant de choisir une base de travail. |
| Liste des pull requests | Consulter les PR ouvertes, fermées ou toutes les PR selon le filtre demandé. |
| Liste des issues | Consulter les issues du dépôt comme point de départ d’un travail. |
Ces actions sont classées en lecture. Elles sont utiles pour comprendre le dépôt et éviter de créer une branche ou une modification à partir d’un contexte supposé.
Créer une branche de travail
Le connecteur peut créer une nouvelle branche dans un dépôt autorisé à partir d’une référence de base existante. La base peut être, par exemple, la branche de développement ou de release utilisée par le projet.
Pour un changement applicatif ou documentaire, le workflow recommandé consiste à créer une branche dédiée plutôt qu’à écrire directement sur la branche cible.
Avant de créer la branche, vérifiez la branche de base, l’objectif du changement et le nom de la branche. La création d’une branche est une écriture distante : elle modifie immédiatement l’état du dépôt GitHub.
Écrire un fichier et créer un commit
Le connecteur GitHub actuel peut créer un nouveau fichier UTF-8 ou remplacer le contenu d’un fichier UTF-8 existant. GitHub crée alors un commit correspondant à cette écriture.
Pour une mise à jour, OrbitWake doit fournir le SHA courant du fichier. Cette contrainte évite d’écraser silencieusement une version que le connecteur n’a pas lue.
Le nom de branche est optionnel au niveau de l’action technique. Dans un workflow contrôlé, indiquez explicitement la branche de travail afin de ne pas écrire par erreur sur la branche par défaut.
git push.Pas de commande push implicite
Dans ce workflow, l’écriture GitHub est déjà distante. Il n’existe donc pas une étape séparée où OrbitWake exécute nécessairement git add, git commit puis git push depuis le workspace Code.
Cette différence doit rester claire dans la documentation et dans l’interface : une écriture via le connecteur GitHub crée un commit, mais cela ne signifie pas que Code expose déjà un terminal Git complet ou un client Git natif.
Le CLI OrbitWake possède sa propre documentation Git pour les opérations observées depuis un environnement de terminal. La surface Code et le connecteur GitHub suivent aujourd’hui un modèle distinct.
Ouvrir une pull request
Le connecteur peut ouvrir une pull request à partir d’une branche source vers une branche cible. Le titre est requis pour une nouvelle PR, et le corps peut expliquer le changement, les tests réalisés et les points à revoir.
Une PR peut aussi être créée en brouillon. Utilisez cet état lorsque le travail doit être partagé sans être considéré comme prêt à merger.
Avant d’ouvrir la PR, relisez le contenu de la branche et assurez-vous que la portée du changement est compréhensible. Une bonne PR doit permettre à une autre personne de comprendre pourquoi le changement existe, pas seulement quels fichiers ont été modifiés.
Revue et CI avant merge
La création d’une PR n’est pas une validation automatique. Les contrôles du dépôt restent applicables : revue humaine, checks GitHub Actions, tests, règles de branche et autres protections configurées côté GitHub.
OrbitWake Code ne doit pas présenter un build interne réussi comme l’équivalent d’une CI GitHub réussie. Le build Code vérifie le travail dans la surface Code ; la CI du dépôt valide ce que le dépôt a réellement reçu.
Avant de merger, attendez les contrôles requis par le dépôt et vérifiez qu’aucun nouveau commit n’a rendu la revue précédente obsolète.
Le merge est une action sensible
Le connecteur GitHub expose une action de merge de pull request. Dans l’implémentation actuelle, cette action est classée comme sensible et passe par le système d’approbation des connecteurs.
Lorsqu’une approbation est nécessaire, l’exécution est suspendue jusqu’à ce que l’utilisateur approuve ou refuse l’action. Une approbation expirée, déjà décidée ou invalide ne peut pas être réutilisée.
Le merge doit rester la dernière étape, après revue du contenu, validation de la CI et confirmation que la branche cible est correcte.
Partir d’une issue
Le connecteur peut lire les issues d’un dépôt et créer une nouvelle issue. Cela permet de documenter un problème ou un besoin avant de passer à la branche et à la PR.
Dans un workflow discipliné, l’issue décrit le problème ou le résultat attendu, la branche contient le changement, et la pull request relie le travail à une revue avant intégration.
La version actuelle ne doit pas être présentée comme un système complet de gestion de projet GitHub : les actions disponibles restent limitées aux opérations explicitement exposées par le connecteur.
Workflow recommandé avec OrbitWake Code
| Étape | Action | Pourquoi |
|---|---|---|
| 1. Travailler dans Code | Construire, prévisualiser et revoir le changement. | Valider l’intention avant d’écrire dans GitHub. |
| 2. Créer un checkpoint | Conserver l’état Code jugé stable. | Disposer d’un retour arrière dans le projet Code. |
| 3. Lire le dépôt GitHub | Vérifier dépôt, branche de base et fichiers concernés. | Éviter de partir d’un contexte obsolète. |
| 4. Créer une branche | Isoler le changement sur GitHub. | Protéger la branche cible. |
| 5. Écrire les fichiers | Créer ou mettre à jour les fichiers sur la branche. | Produire des commits distants explicites. |
| 6. Ouvrir une PR | Soumettre la branche à revue. | Centraliser discussion et validation. |
| 7. Attendre la CI | Contrôler les checks requis. | Distinguer build Code et validation du dépôt. |
| 8. Approuver le merge | Autoriser l’action sensible seulement si tout est prêt. | Éviter un merge automatique après génération. |
Éviter les écrasements et conflits
Pour mettre à jour un fichier existant, le connecteur utilise son SHA courant. Si le fichier change entre la lecture et l’écriture, la mise à jour peut échouer au lieu d’écraser silencieusement la nouvelle version.
En cas d’échec, relisez le fichier et réévaluez le changement avant de réessayer. Ne réutilisez pas un ancien SHA pour forcer une écriture.
Ce mécanisme protège un fichier individuel, mais il ne remplace pas une stratégie complète de résolution de conflits Git entre plusieurs branches.
Permissions et portée des dépôts
Les actions du connecteur sont classées par niveau : lecture, écriture ou sensible. La lecture permet d’inspecter. Les écritures modifient GitHub. Les actions sensibles, comme le merge, nécessitent un contrôle supplémentaire.
OrbitWake peut aussi limiter les dépôts accessibles à une portée spécifique. Un workflow doit toujours utiliser le plus petit ensemble de dépôts nécessaire.
Ces contrôles n’annulent pas les permissions GitHub elles-mêmes. Une action doit être autorisée à la fois par OrbitWake et par les droits réellement accordés à l’installation GitHub.
Limites actuelles
OrbitWake Code ne fournit pas encore dans son éditeur un client Git complet avec index local, staging interactif, rebase, cherry-pick, stash, tags ou résolution visuelle de conflits.
La vue Changes de Code ne doit toujours pas être décrite comme un diff Git complet ligne par ligne. Pour la revue Git formelle, utilisez la pull request et les outils du dépôt.
Le connecteur GitHub actuel travaille principalement avec les dépôts, la recherche de code, les fichiers, les branches, les issues et les pull requests. N’inventez pas de capacité supplémentaire tant qu’elle n’est pas exposée et testée.
Étapes suivantes
Après Workflows Git, la documentation détaillera progressivement les surfaces Agents et Connectors. Pour l’instant, utilisez la page Git du CLI pour les opérations liées au terminal et la documentation Connectors pour les intégrations externes.