Guide d’intégration Git

Apprenez à connecter vos dépôts GitHub aux espaces TeamDay, permettant à vos agents IA de travailler avec le contrôle de version.

Table des matières

• Ce que vous allez apprendre
• Prérequis
• Comprendre Git dans TeamDay
• Configuration OAuth GitHub
• Clonage de dépôts
• Faire des commits
• Travailler avec les branches
• Bonnes pratiques
• Résolution de problèmes

Ce que vous allez apprendre

À la fin de ce guide, vous saurez comment :

• ✅ Configurer l’authentification OAuth GitHub
• ✅ Cloner des dépôts privés dans des espaces
• ✅ Permettre aux agents de faire des commits et de pousser des changements
• ✅ Gérer les branches et les pull requests
• ✅ Configurer les identifiants Git de manière sécurisée
• ✅ Gérer les conflits de fusion

Temps pour compléter : 15-20 minutes

Prérequis

Avant de commencer, assurez-vous d’avoir :

• ✅ Un compte TeamDay (Guide d’inscription)
• ✅ Un espace créé (Guide de configuration d’espace)
• ✅ Un agent créé (Guide d’agent)
• ✅ Un compte GitHub avec des dépôts

Comprendre Git dans TeamDay

Comment fonctionne Git dans les espaces

Les espaces TeamDay ont un support Git intégré, vous permettant de cloner des dépôts, de suivre les changements et de synchroniser avec GitHub directement depuis l’interface.

Chaque espace peut contenir plusieurs dépôts Git. Lorsque vous clonez un dépôt, il est placé dans un sous-répertoire au sein de votre espace, gardant vos projets organisés.

Exemple de structure d’espace :

my-space/
├── CLAUDE.md           # Configuration de l'espace
├── my-webapp/          # Dépôt cloné
│   ├── .git/
│   ├── src/
│   └── package.json
└── another-repo/       # Autre dépôt cloné
    ├── .git/
    └── ...

Fonctionnalités clés

Contrôle de version

• Fonctionnalité Git complète dans chaque espace
• Commit, branch, merge et rebase
• Suivi complet de l’historique

Intégration GitHub

• Authentification OAuth
• Cloner des dépôts privés
• Pousser les changements vers GitHub
• Gestion automatique des identifiants

Capacités des agents

• Les agents peuvent lire les fichiers de dépôt
• Faire des commits avec des messages significatifs
• Créer et changer de branches
• Pousser vers les dépôts distants

Configuration OAuth GitHub

Avant de pouvoir cloner des dépôts privés, vous devez connecter votre compte GitHub à TeamDay.

Autoriser l’accès GitHub

Étape 1 : Accéder aux paramètres de l’espace

1. Ouvrir votre espace
2. Aller dans l’onglet Paramètres
3. Cliquer sur “Intégrations” dans la barre latérale
4. Trouver la section “GitHub”

Étape 2 : Connecter GitHub

1. Cliquer sur le bouton “Connecter GitHub”

2. Vous serez redirigé vers GitHub

3. Examiner les permissions demandées :

   • ✅ Accès en lecture/écriture aux dépôts
   • ✅ Lire le profil utilisateur
   • ✅ Accès aux dépôts privés

4. Cliquer sur “Autoriser TeamDay”

Étape 3 : Confirmer la connexion

Après autorisation :

• Vous serez redirigé vers TeamDay
• Le statut affiche “GitHub Connecté” avec une coche verte
• Votre nom d’utilisateur GitHub est affiché
• Vous pouvez maintenant cloner des dépôts privés

Permissions accordées :

Gérer la connexion GitHub

Voir le statut de connexion :

Paramètres → Intégrations → GitHub

Affiche :

• Nom d’utilisateur connecté
• Date de dernière authentification
• Expiration du token (90 jours)
• Scopes accordés

Déconnecter GitHub :

1. Paramètres → Intégrations → GitHub
2. Cliquer sur “Déconnecter”
3. Confirmer la déconnexion

Reconnecter GitHub :

Si votre token expire (après 90 jours) :

1. Vous verrez un avertissement “GitHub Déconnecté”
2. Cliquer sur “Reconnecter”
3. Réautoriser sur GitHub

Rafraîchissement du token

Les tokens GitHub se rafraîchissent automatiquement :

• Token d’accès : 15 minutes
• Token de rafraîchissement : 90 jours

TeamDay gère cela automatiquement. Vous devrez seulement vous réautoriser si le token de rafraîchissement expire.

Clonage de dépôts

Cloner un dépôt public

Via l’interface :

1. Ouvrir votre espace → panneau Fichiers
2. Cliquer sur le bouton ”+” dans la barre d’outils
3. Sélectionner “Cloner un dépôt”
4. Entrer l’URL du dépôt :

   https://github.com/username/public-repo.git

5. (Optionnel) Spécifier la branche (défaut : main)
6. (Optionnel) Spécifier le répertoire de destination
7. Cliquer sur “Cloner”

Via un agent :

Demandez à votre agent de cloner :

Utilisateur : "Clone le dépôt https://github.com/user/repo.git"

Agent : [Exécute la commande git clone]

Via l’API :

curl -X POST "https://us.teamday.ai/api/v1/spaces/s-abc123/init" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "gitUrl": "https://github.com/username/repo.git",
    "gitBranch": "main",
    "directory": "my-project"
  }'

Cloner un dépôt privé

Prérequis :

• ✅ OAuth GitHub connecté (voir Configuration OAuth GitHub)

Via l’interface :

1. Ouvrir l’espace → panneau Fichiers

2. Cliquer sur ”+” → “Cloner un dépôt”

3. Entrer l’URL du dépôt privé :

   https://github.com/username/private-repo.git

4. Si GitHub n’est pas connecté :

   • Vous verrez l’invite : “Connectez GitHub pour cloner des dépôts privés”
   • Cliquer sur “Connecter GitHub”
   • Compléter le flux OAuth
   • Retourner au modal de clonage

5. Si GitHub est connecté :

   • Une coche verte affiche “GitHub Connecté”
   • Cliquer sur “Cloner”

Via un agent :

Utilisateur : "Clone mon dépôt privé https://github.com/myorg/private-api.git"

Agent : [Utilise le token OAuth GitHub pour cloner]

Via l’API :

curl -X POST "https://us.teamday.ai/api/v1/spaces/s-abc123/init" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "gitUrl": "https://github.com/username/private-repo.git",
    "useGitHubAuth": true
  }'

Progression du clonage

Suivre la progression du clonage :

Dans l’interface :

• La barre de progression affiche le pourcentage
• Mises à jour de statut : “Récupération des objets…”, “Résolution des deltas…”
• Prend généralement 5-30 secondes selon la taille du dépôt

Dans le terminal (si utilisation d’un agent) :

Clonage dans 'repo-name'...
remote: Énumération des objets : 1234, fait.
remote: Comptage des objets : 100% (1234/1234), fait.
remote: Compression des objets : 100% (890/890), fait.
Réception des objets : 100% (1234/1234), 5.67 MiB | 8.90 MiB/s, fait.
Résolution des deltas : 100% (456/456), fait.

Via l’API - Interroger le statut :

curl -X GET "https://us.teamday.ai/api/v1/spaces/s-abc123/environment" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN"

Réponse :

{
  "status": "cloning",
  "progress": 67,
  "message": "Résolution des deltas..."
}

Panneau Git

Le panneau Git apparaît en haut de la barre latérale Fichiers et affiche le statut du répertoire racine de votre espace.

États du panneau

Pas de dépôt Git

• Apparaît lorsque la racine de l’espace n’a pas Git initialisé
• Vous pouvez soit :
  • Cloner un dépôt en utilisant le bouton + (recommandé)
  • Initialiser Git dans la racine de l’espace pour suivre les fichiers libres

Dépôt Git actif

• Affiche le nom de la branche actuelle
• Affiche le nombre de changements (staged + unstaged + untracked)
• Affiche les indicateurs ahead/behind pour le statut de synchronisation distante

Expansion du panneau

Cliquer sur l’en-tête du panneau Git pour l’étendre et voir :

• L’URL du dépôt distant
• La liste des fichiers modifiés (staged, modifiés, non suivis)
• Les contrôles de commit et de synchronisation

Faire des commits

Voir le statut Git

Via l’interface - Panneau Git :

1. Ouvrir l’espace → panneau Fichiers
2. Développer le Panneau Git en haut
3. Voir le statut :
   • Nom de la branche actuelle
   • Nombre de fichiers modifiés
   • Nombre de changements staged
   • Indicateurs ahead/behind

Via un agent :

Utilisateur : "Vérifie le statut git"

Agent : [Exécute : git status]

Sortie :
Sur la branche main
Votre branche est à jour avec 'origin/main'.

Changements non indexés pour le commit :
  modifié :   src/api/users.ts
  modifié :   README.md

Fichiers non suivis :
  src/utils/helpers.ts

Via l’API :

curl -X POST "https://us.teamday.ai/api/v1/devenv/org-abc/s-space123/exec" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "git status --short"
  }'

Indexer les changements

Via l’interface :

1. Développer le panneau Git
2. Examiner les fichiers modifiés
3. Options :
   • Tout indexer - Indexer tout
   • Indexer le fichier - Cliquer sur la case à cocher à côté du fichier
   • Désindexer - Décocher le fichier indexé

Via un agent :

Utilisateur : "Indexe tous les changements"

Agent : [Exécute : git add .]

Utilisateur : "Indexe seulement le fichier src/api/users.ts"

Agent : [Exécute : git add src/api/users.ts]

Indexation sélective :

Utilisateur : "Indexe tous les fichiers TypeScript sauf les tests"

Agent : [Exécute : git add src/**/*.ts && git reset src/**/*.test.ts]

Créer des commits

Via l’interface :

1. Indexer vos changements (voir ci-dessus)
2. Entrer le message de commit dans la zone de texte :

   Ajouter la validation utilisateur aux endpoints API
   
   - Implémenter la validation des emails
   - Ajouter des vérifications de force de mot de passe
   - Retourner des messages d'erreur détaillés

3. Cliquer sur le bouton “Commit”

Via un agent :

Les agents peuvent créer des commits avec des messages significatifs :

Utilisateur : "Fais un commit de ces changements avec un bon message"

Agent : [Analyse les changements, crée le commit]

Exécute : git commit -m "Ajouter la validation d'entrée à l'API utilisateur

- Implémenter la validation du format d'email
- Ajouter les exigences de force de mot de passe
- Retourner des messages d'erreur conviviaux
- Ajouter des tests unitaires pour la logique de validation"

Via l’API :

curl -X POST "https://us.teamday.ai/api/v1/devenv/org-abc/s-space123/exec" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "git commit -m \"Ajouter la validation utilisateur\""
  }'

Bonnes pratiques pour les messages de commit

Bons messages de commit :

✅ Ajouter des endpoints d'authentification utilisateur

✅ Corriger la vulnérabilité d'injection SQL dans la requête utilisateur

✅ Refactoriser le pooling de connexions à la base de données
- Utiliser un pool de connexions pour de meilleures performances
- Ajouter la configuration du timeout de connexion
- Implémenter une logique de retry automatique

✅ Mettre à jour les dépendances aux dernières versions
- React 18.2.0 → 18.3.0
- TypeScript 5.0.0 → 5.3.0
- Corriger les changements majeurs dans l'API

Mauvais messages de commit :

❌ mise à jour trucs
❌ fix
❌ wip
❌ asdfasdf
❌ changements

Format :

<type>: <sujet>

<corps>

<pied>

Types :

• feat: - Nouvelle fonctionnalité
• fix: - Correction de bug
• docs: - Documentation
• refactor: - Restructuration du code
• test: - Ajout/mise à jour de tests
• chore: - Tâches de maintenance

Pousser vers le distant

Via l’interface :

1. Après le commit, le panneau Git affiche ”↑ 1” (commits en avance)
2. Cliquer sur le bouton “Push”
3. Les changements sont poussés vers GitHub

Via un agent :

Utilisateur : "Pousse mes commits vers GitHub"

Agent : [Exécute : git push origin main]

Via l’API :

curl -X POST "https://us.teamday.ai/api/v1/devenv/org-abc/s-space123/exec" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "git push origin main"
  }'

Premier push (définir l’upstream) :

git push -u origin main

TeamDay définit automatiquement l’upstream au premier push.

Tirer les mises à jour

Via l’interface :

1. Le panneau Git affiche ”↓ 2” (commits en retard)
2. Cliquer sur le bouton “Pull”
3. Les derniers changements sont récupérés et fusionnés

Via un agent :

Utilisateur : "Tire les derniers changements depuis GitHub"

Agent : [Exécute : git pull origin main]

Via l’API :

curl -X POST "https://us.teamday.ai/api/v1/devenv/org-abc/s-space123/exec" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "git pull origin main"
  }'

Voir l’historique des commits

Via l’interface :

1. Ouvrir l’espace → onglet Historique
2. Voir les commits avec :
   • Message de commit
   • Auteur et date
   • Fichiers modifiés
   • Vue diff

Via un agent :

Utilisateur : "Montre l'historique récent des commits"

Agent : [Exécute : git log --oneline -10]

Sortie :
abc1234 Ajouter la validation utilisateur
def5678 Corriger le bug d'authentification
ghi9012 Mettre à jour les dépendances
...

Via l’API :

curl -X GET "https://us.teamday.ai/api/v1/spaces/s-space123/git/log" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN"

Travailler avec les branches

Créer des branches

Via un agent :

Utilisateur : "Crée une nouvelle branche appelée 'feature/add-auth'"

Agent : [Exécute : git checkout -b feature/add-auth]

Via l’API :

curl -X POST "https://us.teamday.ai/api/v1/devenv/org-abc/s-space123/exec" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "git checkout -b feature/add-auth"
  }'

Changer de branches

Via un agent :

Utilisateur : "Passe à la branche main"

Agent : [Exécute : git checkout main]

Fusionner des branches

Via un agent :

Utilisateur : "Fusionne feature/add-auth dans main"

Agent : [Exécute la séquence :
  git checkout main
  git merge feature/add-auth
]

Supprimer des branches

Via un agent :

Utilisateur : "Supprime la branche feature/add-auth"

Agent : [Exécute : git branch -d feature/add-auth]

Ajouter un distant

Si vous avez initialisé Git localement et voulez vous connecter à un distant :

Via un agent :

Utilisateur : "Ajoute le distant Git : git remote add origin https://github.com/user/repo.git"

Agent : [Exécute : git remote add origin https://github.com/user/repo.git]

Via l’API :

curl -X POST "https://us.teamday.ai/api/v1/devenv/org-abc/s-space123/exec" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "git remote add origin https://github.com/user/repo.git"
  }'

Bonnes pratiques

1. Faites des commits tôt et souvent

À faire :

✅ Petits commits focalisés
✅ Commit après chaque changement logique
✅ Facile à réviser et à annuler

Exemple de mission :

Commit 1 : Ajouter le modèle utilisateur
Commit 2 : Ajouter la validation utilisateur
Commit 3 : Ajouter les endpoints API utilisateur
Commit 4 : Ajouter les tests utilisateur

À ne pas faire :

❌ Un commit géant en fin de journée
❌ Mélanger des changements non liés
❌ Commiter du code cassé

2. Écrire des messages de commit significatifs

Bon :

feat: Ajouter l'authentification JWT à l'API utilisateur

- Implémenter la génération de token à la connexion
- Ajouter un middleware pour vérifier les tokens
- Inclure la logique de refresh token
- Ajouter des tests pour le flux d'authentification

Mauvais :

mises à jour
corriger des trucs
travail en cours

3. Tirez avant de pousser

Synchronisez toujours avant de pousser :

Utilisateur : "Tire les derniers changements puis pousse mes commits"

Agent : [Exécute :
  git pull origin main
  git push origin main
]

Évite les conflits de fusion et garde l’historique propre.

4. Utilisez des branches pour les fonctionnalités

Créez des branches de fonctionnalité :

main (stable)
  ├── feature/add-auth (nouvelle fonctionnalité)
  ├── feature/user-profile (autre fonctionnalité)
  └── hotfix/login-bug (correction urgente)

Mission :

Utilisateur : "Crée la branche feature/add-auth et implémente l'authentification"

Agent : [Crée la branche, implémente la fonctionnalité]

Utilisateur : "Fusionne dans main quand c'est fait"

Agent : [Fusionne et supprime la branche]

5. Gardez la branche main stable

Règles de la branche main :

• ✅ Toujours déployable
• ✅ Tous les tests passent
• ✅ Code révisé
• ✅ Pas de commits WIP

Règles de branche de fonctionnalité :

• ✅ Travail en cours OK
• ✅ Expérimentez librement
• ✅ Squash avant de fusionner

6. Révisez les changements avant de commiter

Utilisateur : "Montre-moi quels changements je vais commiter"

Agent : [Exécute : git diff --staged]

Attrapez les erreurs avant qu’elles ne soient commitées.

7. Utilisez .gitignore

Ignorez toujours :

# Dépendances
node_modules/
.env
.env.local

# Sorties de build
dist/
.next/

# Logs
*.log

# OS
.DS_Store

8. Protégez les données sensibles

Ne commitez jamais :

• ❌ Clés API ou secrets
• ❌ Mots de passe
• ❌ Clés privées
• ❌ Identifiants de base de données

Utilisez plutôt :

• ✅ Variables d’environnement
• ✅ Secrets TeamDay
• ✅ Fichiers .env (dans .gitignore)

Travailler avec les agents IA

Les agents IA dans votre espace peuvent utiliser les commandes Git directement.

Ce que les agents peuvent faire

Lire l’état du dépôt :

Utilisateur : "Quels fichiers ont changé ?"
Utilisateur : "Montre-moi les 5 derniers commits"
Utilisateur : "Vérifie si nous sommes en avance sur le distant"

Faire des commits :

Utilisateur : "Fais un commit de ces changements avec un message descriptif"

Agent : [Analyse les changements, écrit un message de commit significatif]

Gérer les branches :

Utilisateur : "Crée une branche de fonctionnalité pour l'authentification"
Utilisateur : "Fusionne ma branche de fonctionnalité dans main"
Utilisateur : "Supprime les vieilles branches de fonctionnalité"

Synchroniser avec le distant :

Utilisateur : "Tire les derniers changements"
Utilisateur : "Pousse mes commits vers GitHub"

Mission Git d’agent

Exemple : Ajouter une fonctionnalité

Utilisateur : "Implémente l'authentification utilisateur, fais un commit et pousse"

Agent :
1. Crée une branche de fonctionnalité
2. Implémente le code d'authentification
3. Écrit les tests
4. Fait un commit avec le message : "Ajouter l'authentification JWT"
5. Pousse vers GitHub
6. Rapporte la complétion

Instructions Git CLAUDE.md

Ajoutez des conseils Git à votre CLAUDE.md :

## Mission Git

### Avant de commiter
1. Exécuter les tests : `bun test`
2. Vérifier le lint : `bun run lint`
3. Revoir les changements : `git diff`

### Format de message de commit

:

## Résolution de problèmes

### "Not a git repository"

**Problème :** La racine de l'espace n'a pas Git initialisé

**Solutions :**

1. **Initialiser Git :**

2. **Naviguer vers le dépôt cloné :**

### Échec d'authentification

**Problème :** Impossible de cloner un dépôt privé

**Solutions :**

1. **Vérifier la connexion GitHub :**
   - Paramètres → Intégrations → GitHub
   - Devrait afficher le statut "Connecté"

2. **Reconnecter GitHub :**
   - Cliquer sur "Déconnecter"
   - Cliquer sur "Connecter"
   - Réautoriser

3. **Vérifier l'accès au dépôt :**
   - Aller sur GitHub.com
   - Vérifier que vous avez accès au dépôt
   - Vérifier que l'URL du dépôt est correcte

### Timeout de clonage

**Problème :** Un grand dépôt expire

**Solutions :**

1. **Clonage superficiel :**

2. **Cloner une branche spécifique :**

### Conflits de fusion

**Problème :** Conflits lors du pull ou de la fusion

**Solutions :**

1. **Voir les conflits :**

2. **Résoudre les conflits :**

3. **Abandonner la fusion si nécessaire :**

### Secrets commitées accidentellement

**Problème :** Clés API ou mots de passe commitées

**Solutions :**

1. **Si pas encore poussé :**

2. **Si déjà poussé :**

**IMPORTANT :** Faites toujours tourner les secrets exposés immédiatement !

### Push rejeté

**Problème :** `! [rejected] main -> main (non-fast-forward)`

**Solution :**

## Bonnes pratiques de sécurité

### 1. Ne commitez jamais de secrets

**Ajouter à .gitignore :**
```ini
.env
.env.local
.env.*.local
*.key
*.pem
secrets.json
credentials.json

DATABASE_URL=postgresql://...
API_KEY=sk-...

const apiKey = process.env.API_KEY;

Utilisateur : "Montre-moi ce que je vais pousser"

Agent : [Exécute : git log origin/main..HEAD]