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.