Configuration Git sous Windows avec GitHub / GitLab, token et Visual Studio Code

Cette procédure décrit la configuration d'un poste Windows pour travailler avec des dépôts Git hébergés sur  GitHub ou GitLab , depuis Git Bash et Visual Studio Code. 
 La méthode présentée utilise HTTPS et un Personal Access Token (PAT) ou un token équivalent, associé à Git Credential Manager (GCM) . 
 1. Principe général 
 GitHub et GitLab peuvent utiliser une authentification différente de celle utilisée pour accéder à leur interface Web. 
 Lorsque l'authentification par mot de passe classique n'est pas disponible, notamment avec le SSO ou la double authentification, un token est utilisé pour les opérations Git en HTTPS. 
 Visual Studio Code / Git Bash
 |
 | HTTPS
 v
 Git Credential Manager
 |
 | Token
 v
 GitHub ou GitLab 
 Git Credential Manager permet de gérer les informations d'authentification sans avoir à stocker manuellement le token dans un fichier texte ou dans l'URL du dépôt. 
 2. Prérequis 
 
 Windows. 
 Un compte GitHub ou GitLab. 
 Les droits nécessaires sur le dépôt concerné. 
 Git installé. 
 Git Credential Manager installé. 
 Visual Studio Code installé. 
 
 3. Choisir GitHub ou GitLab 
 La procédure Git est quasiment identique pour GitHub et GitLab. La principale différence concerne la création et les permissions du token. 
 
 
 
 Plateforme 
 Authentification Git HTTPS 
 Token 
 
 
 
 
 GitHub 
 HTTPS 
 Personal Access Token 
 
 
 GitLab 
 HTTPS 
 Personal Access Token 
 
 
 
 4. Créer le token 
 Le token doit être créé depuis les paramètres du compte de la plateforme utilisée. 
 4.1 GitHub 
 Dans GitHub, accéder aux paramètres du compte puis à la gestion des Personal Access Tokens . 
 GitHub propose notamment les tokens Fine-grained , qui permettent de limiter les permissions à certains dépôts et à certaines opérations. 
 Pour un usage Git classique, accorder uniquement les permissions nécessaires à la lecture et à l'écriture des dépôts concernés. 
 4.2 GitLab 
 Dans GitLab, accéder au profil puis à : 
 Edit profile
 |
 +--> Access
 |
 +--> Personal access tokens 
 Pour un usage Git HTTPS classique, le scope write_repository permet les opérations de lecture et d'écriture nécessaires au dépôt. 
 5. Bonnes pratiques pour le token 
 Donner au token uniquement les permissions nécessaires. 
 Pour un usage Git classique : 
 clone
fetch
pull
push 
 il faut disposer de droits permettant au minimum la lecture du dépôt et, pour le push, de droits d'écriture. 
 Bonne pratique : ne pas donner une permission globale de type API lorsque les seules opérations nécessaires sont les opérations Git classiques. 
 Expiration 
 Lorsque la plateforme le permet, définir une date d'expiration adaptée à la politique de sécurité de l'organisation. 
 Stockage du token 
 ATTENTION : un token est une donnée secrète. Ne jamais le communiquer par email, messagerie instantanée, ticket ou dépôt Git. 
 Le token complet peut n'être affiché qu'au moment de sa création. Le conserver temporairement dans un gestionnaire de mots de passe ou de secrets si nécessaire. 
 6. Installer et vérifier Git 
 Ouvrir Git Bash ou le terminal intégré de Visual Studio Code. 
 Vérifier la version de Git : 
 git --version 
 Exemple : 
 git version 2.49.0.windows.1 
 Une version récente de Git pour Windows inclut généralement Git Credential Manager. 
 7. Vérifier Git Credential Manager 
 Vérifier sa présence : 
 git credential-manager --version 
 Exemple : 
 2.6.1 
 Effectuer ensuite un diagnostic : 
 git credential-manager diagnose 
 Le résultat doit notamment indiquer que le stockage des credentials fonctionne. 
 8. Vérifier le credential helper Git 
 Exécuter : 
 git config --show-origin --get-all credential.helper 
 Un résultat contenant : 
 manager 
 indique que Git utilise Git Credential Manager. 
 Exemple : 
 file:C:/Program Files/Git/etc/gitconfig manager 
 9. Ne pas créer manuellement .gitcredentials 
 Lorsque Git Credential Manager est installé et configuré, il n'est pas nécessaire de créer manuellement un fichier .gitcredentials . 
 Il est déconseillé d'utiliser une configuration qui stocke le token directement dans un fichier texte en clair. 
 À éviter : 
 ~/.git-credentials 
 contenant directement un token. 
 Il est également déconseillé de mettre le token directement dans l'URL du dépôt. 
 À éviter : 
 https://username:token@serveur.example/repository.git 
 Important : ne jamais mettre un Personal Access Token directement dans une commande git clone , une URL Git, un script ou un fichier de configuration versionné. 
 10. Configurer l'identité Git 
 Le nom et l'adresse email Git sont utilisés pour identifier l'auteur des commits. Ils sont indépendants du token utilisé pour s'authentifier. 
 10.1 Vérifier la configuration 
 git config --global user.name
git config --global user.email 
 10.2 Configurer le nom 
 git config --global user.name "Prénom Nom" 
 10.3 Configurer l'adresse email 
 git config --global user.email "prenom.nom@example.com" 
 Utiliser une adresse email reconnue par la plateforme Git utilisée lorsque cela est nécessaire pour associer correctement les commits au compte. 
 11. Récupérer l'URL HTTPS du dépôt 
 Ouvrir le dépôt dans GitHub ou GitLab. 
 Rechercher l'option permettant de cloner le dépôt puis sélectionner HTTPS . 
 Une URL peut ressembler à : 
 https://github.com/organisation/projet.git 
 ou : 
 https://gitlab.example.com/groupe/projet.git 
 L'URL exacte dépend de la plateforme et du serveur utilisé. 
 12. Créer un répertoire local 
 Créer un répertoire destiné aux dépôts Git. 
 Exemple : 
 mkdir ~/Github 
 Se positionner dans le répertoire : 
 cd ~/Github 
 Le nom du répertoire est libre. Il peut par exemple être : 
 ~/Github
~/Git
~/Repositories
~/Dev 
 13. Cloner un dépôt 
 Utiliser l'URL HTTPS fournie par GitHub ou GitLab. 
 Exemple GitHub : 
 git clone https://github.com/organisation/projet.git 
 Exemple GitLab : 
 git clone https://gitlab.example.com/groupe/projet.git 
 Git peut alors demander les informations d'authentification. 
 14. Authentification avec le token 
 Lors de la première connexion, Git Credential Manager peut ouvrir une fenêtre d'authentification. 
 Si Git demande directement les credentials dans le terminal : 
 
 
 
 Champ 
 Valeur 
 
 
 
 
 Username 
 Nom d'utilisateur du compte 
 
 
 Password 
 Personal Access Token 
 
 
 
 Attention : dans le champ Password, saisir le token et non le mot de passe du compte. 
 15. Fonctionnement de Git Credential Manager 
 Lors du premier accès : 
 git pull / git clone
 |
 v
Git Credential Manager
 |
 v
Authentification
 |
 v
Stockage sécurisé des credentials 
 Lors des accès suivants : 
 git pull / git push
 |
 v
Git Credential Manager
 |
 v
Credential déjà enregistré
 |
 v
Serveur Git 
 Le token n'a donc normalement pas besoin d'être saisi à chaque opération. 
 16. Vérifier le dépôt cloné 
 Entrer dans le répertoire du dépôt : 
 cd projet 
 Vérifier l'URL du dépôt distant : 
 git remote -v 
 Exemple : 
 origin https://github.com/organisation/projet.git (fetch)
origin https://github.com/organisation/projet.git (push) 
 Ou avec GitLab : 
 origin https://gitlab.example.com/groupe/projet.git (fetch)
origin https://gitlab.example.com/groupe/projet.git (push) 
 17. Tester le pull 
 git pull 
 Si le dépôt est déjà à jour : 
 Already up to date. 
 Sinon, Git récupère les modifications disponibles sur le serveur. 
 18. Tester le statut du dépôt 
 git status 
 Exemple de résultat : 
 On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean 
 19. Modifier un fichier 
 Modifier normalement les fichiers du projet avec Visual Studio Code. 
 Après modification, vérifier l'état : 
 git status 
 Les fichiers modifiés apparaissent alors dans la liste des changements. 
 20. Ajouter les modifications 
 Ajouter un fichier précis : 
 git add fichier.txt 
 Ajouter toutes les modifications : 
 git add . 
 Vérifier ensuite : 
 git status 
 21. Créer un commit 
 git commit -m "Description de la modification" 
 Utiliser un message de commit suffisamment explicite pour comprendre la modification effectuée. 
 22. Envoyer les modifications 
 git push 
 Git envoie alors les commits locaux vers le dépôt distant. 
 23. Workflow Git quotidien 
 # Récupérer les dernières modifications
git pull

# Vérifier l'état du dépôt
git status

# Modifier les fichiers

# Ajouter les modifications
git add .

# Créer le commit
git commit -m "Description de la modification"

# Envoyer les modifications
git push 
 24. Utiliser Git avec Visual Studio Code 
 Visual Studio Code utilise directement l'installation Git présente sur le poste. 
 Il n'est donc pas nécessaire d'installer un deuxième Git uniquement pour VS Code. 
 24.1 Ouvrir un dépôt 
 Depuis Git Bash : 
 cd ~/Github/projet
code . 
 Le dépôt est alors ouvert dans Visual Studio Code. 
 24.2 Source Control 
 Dans Visual Studio Code, sélectionner l'icône Source Control dans la barre latérale gauche. 
 Les fichiers modifiés apparaissent dans la section Changes . 
 24.3 Stage / git add 
 Cliquer sur le bouton + à côté d'un fichier permet de le placer dans la zone de staging. 
 Cela correspond à : 
 git add fichier 
 24.4 Commit 
 Entrer le message de commit puis sélectionner Commit . 
 Cela correspond à : 
 git commit -m "Description de la modification" 
 24.5 Pull 
 Utiliser l'action Pull disponible dans les commandes Git de Visual Studio Code. 
 Équivalent terminal : 
 git pull 
 24.6 Push 
 Utiliser Push ou Sync Changes , selon la version de Visual Studio Code. 
 Équivalent terminal : 
 git push 
 25. Correspondance VS Code / Git 
 
 
 
 Action dans VS Code 
 Commande Git 
 
 
 
 
 Afficher les changements 
 git status 
 
 
 Stage d'un fichier 
 git add fichier 
 
 
 Stage de tous les fichiers 
 git add . 
 
 
 Commit 
 git commit -m "..." 
 
 
 Pull 
 git pull 
 
 
 Push 
 git push 
 
 
 
 26. Plusieurs dépôts 
 Il est possible d'utiliser le même compte et le même mécanisme d'authentification pour plusieurs dépôts accessibles avec ce compte, dans la limite des permissions accordées au token. 
 Exemple : 
 Github/
├── projet-a/
├── projet-b/
├── projet-c/
└── projet-d/ 
 Chaque dépôt possède son propre répertoire .git . 
 Le répertoire .git est créé automatiquement par Git lors d'un git clone . 
 27. Fichiers et éléments à ne pas créer manuellement 
 
 
 
 Élément 
 Action 
 
 
 
 
 .git 
 Ne pas créer manuellement. Git le crée automatiquement. 
 
 
 .gitcredentials 
 Ne pas créer manuellement lorsque Git Credential Manager est utilisé. 
 
 
 Token dans une URL 
 À éviter. 
 
 
 Token dans un script 
 À éviter. 
 
 
 Token dans un dépôt Git 
 Interdit. 
 
 
 
 28. Vérification complète de la configuration 
 Les commandes suivantes permettent de vérifier la configuration du poste : 
 # Version Git
git --version

# Version Git Credential Manager
git credential-manager --version

# Diagnostic Git Credential Manager
git credential-manager diagnose

# Credential helper utilisé
git config --show-origin --get-all credential.helper

# Identité Git
git config --global user.name
git config --global user.email

# Remote du dépôt
git remote -v

# Etat du dépôt
git status 
 29. Dépannage 
 29.1 Git demande le token à chaque opération 
 Vérifier le credential helper : 
 git config --show-origin --get-all credential.helper 
 Vérifier également Git Credential Manager : 
 git credential-manager diagnose 
 Si le stockage des credentials est fonctionnel mais que l'authentification est systématiquement redemandée, vérifier l'URL du remote et les credentials enregistrés pour le serveur concerné. 
 29.2 Le token est refusé 
 Vérifier : 
 
 que le token n'est pas expiré ; 
 que le token n'a pas été révoqué ; 
 que le token possède les permissions nécessaires ; 
 que le compte possède les droits nécessaires sur le dépôt ; 
 que le bon serveur Git est utilisé ; 
 que le token est utilisé comme mot de passe. 
 
 29.3 Le pull fonctionne mais le push échoue 
 Ce cas indique généralement un problème de droits d'écriture. 
 Vérifier les permissions du token et les droits du compte sur le dépôt. 
 29.4 Vérifier l'URL du dépôt 
 git remote -v 
 Vérifier que l'URL correspond bien au dépôt attendu et utilise HTTPS. 
 30. Sécurité 
 
 Ne jamais communiquer un Personal Access Token. 
 Ne jamais mettre un token dans une URL Git. 
 Ne jamais mettre un token dans un script en clair. 
 Ne jamais committer un token dans un dépôt. 
 Utiliser une date d'expiration lorsque cela est possible. 
 Utiliser les permissions minimales nécessaires. 
 Révoquer immédiatement un token suspect ou compromis. 
 Utiliser Git Credential Manager pour la gestion des credentials. 
 
 31. Extension GitHub / GitLab pour Visual Studio Code 
 Les opérations Git classiques ne nécessitent pas obligatoirement l'extension spécifique à la plateforme. 
 Pour : 
 clone
pull
add
commit
push 
 Git + Git Credential Manager + Visual Studio Code suffisent. 
 Les extensions GitHub ou GitLab peuvent être ajoutées pour bénéficier de fonctionnalités supplémentaires propres à la plateforme, comme les Pull Requests, Merge Requests, Issues ou Pipelines. 
 Les permissions nécessaires au token peuvent alors être différentes de celles nécessaires uniquement pour les opérations Git. 
 32. Architecture recommandée 
 GitHub / GitLab
 ^
 |
 HTTPS
 |
 |
 Git Credential Manager
 ^
 |
 |
 Git / Visual Studio Code
 ^
 |
 |
 Repository local 
 33. Workflow recommandé 
 SERVEUR GIT
 GitHub / GitLab
 ^
 |
 push
 |
 ┌────┴────┐
 │ COMMIT │
 └────┬────┘
 ^
 |
 git add
 ^
 |
 MODIFICATIONS
 ^
 |
 git pull
 |
 v
 SERVEUR GIT 
 34. Résumé 
 Pour travailler avec GitHub ou GitLab sous Windows, la configuration recommandée est : 
 Git
 +
HTTPS
 +
Personal Access Token
 +
Git Credential Manager
 +
Visual Studio Code 
 Une fois la configuration terminée, le workflow quotidien se limite généralement aux commandes suivantes : 
 git pull

git add .

git commit -m "Description de la modification"

git push 
 Configuration recommandée : utiliser HTTPS avec un token disposant des permissions minimales nécessaires, laisser Git Credential Manager gérer l'authentification et ne jamais stocker manuellement le token dans .gitcredentials , une URL, un script ou un dépôt Git.