Accueil / Mettre un projet sur GitHub

Mettre un projet sous Git et le publier sur GitHub

De git init à un site live sur GitHub Pages : le parcours pas à pas tiré d'un cas réel, pour transformer un dossier de fichiers en projet versionné et publié en ligne.

Walkthrough complet Cas réel anonymisé

À quoi ça sert

Tu as un projet local (un dossier avec du code, des fichiers HTML, des notebooks…) et tu veux :

  • Versionner ton travail pour pouvoir revenir en arrière, suivre les évolutions, expérimenter sans casser.
  • Sauvegarder ton projet ailleurs que sur ton seul PC.
  • Partager avec d'autres (camarades de promo, formateurs, recruteurs).
  • Publier un site statique gratuitement via GitHub Pages.

Cette fiche couvre exactement ce parcours : partir d'un dossier non versionné, et aboutir à un projet hébergé sur GitHub avec un site en ligne.

Différence avec la fiche GitHub

La fiche GitHub présente l'écosystème (Git, compte, SSH, commandes). Cette fiche-ci enchaîne les étapes concrètes pour publier un projet existant, dans l'ordre où tu les rencontres en pratique.

Un exemple d'usage

Tu as bossé une semaine sur un mini-site statique en local. Tu veux le partager avec ta promo et l'avoir en ligne. En une heure, tu peux :

  1. Initialiser Git dans le dossier (git init).
  2. Faire un premier commit qui capture l'état actuel.
  3. Créer un dépôt vide sur GitHub.
  4. Pousser ton commit vers ce dépôt.
  5. Activer GitHub Pages pour avoir une URL publique.

Le site est en ligne, ton code est versionné, et chaque modification future se résume à add → commit → push.

How-to : du dossier local au site en ligne

Pré-requis : Git installé localement et un compte GitHub. Si ce n'est pas le cas, commence par la fiche GitHub.

  1. Vérifier la cohérence du projet local

    Avant de versionner, range. Si tu as renommé le dossier ou refactoré, vérifie qu'il ne reste pas de chemins cassés, de vieux liens vers un ancien nom, ou de fichiers orphelins. Une recherche rapide sur l'ancien nom suffit souvent à débusquer les incohérences.

    Pourquoi maintenant

    Mieux vaut corriger avant le premier commit que de polluer l'historique avec un commit "fix renommage" cinq minutes plus tard.

  2. Créer un .gitignore adapté

    Le .gitignore liste les fichiers et dossiers que Git doit ignorer. À créer avant le premier git add, sinon tu risques de pousser des fichiers sensibles (secrets, env locaux) ou volumineux (caches, dépendances, données).

    Exemple de .gitignore polyvalent pour un projet qui peut évoluer :

    .gitignore 
    # OS
.DS_Store
Thumbs.db

# IDE
.vscode/
.idea/

# Secrets & variables d'environnement
.env
.env.*
!.env.example
*.pem
*.key

# Python
__pycache__/
*.py[cod]
.venv/
venv/
.pytest_cache/
.mypy_cache/
.ruff_cache/
.ipynb_checkpoints/

# Node
node_modules/

# Build / dist
dist/
build/

# Données & modèles ML
data/
models/
*.csv
*.pkl
mlruns/
    Si un fichier sensible est déjà commité

    Ajouter une ligne au .gitignore ne le retire pas de l'historique. Il faut désindexer (git rm --cached <fichier>) puis recommiter, et considérer le secret comme compromis (à régénérer).

  3. Créer un README.md minimal

    Le README est la première chose qu'on voit sur la page GitHub du projet. Inutile d'écrire un roman pour démarrer : titre, une description courte, comment consulter, auteur. Ça suffit.

    markdown 
    # <Mon projet>

Description courte du projet en une phrase ou deux.

## Consultation

- En ligne : https://<ton-pseudo>.github.io/<mon-projet>/
- En local : ouvrir `index.html` dans un navigateur

## Auteur

<Ton nom ou pseudo>

  4. Initialiser Git dans le dossier

    bash 
    git init
git status

    git init crée un sous-dossier .git/ qui contient toute la mécanique du versioning (commits, branches, config locale). Tant que tu ne supprimes pas ce dossier, ton historique est conservé.

    git status doit déjà tenir compte de ton .gitignore : les fichiers ignorés n'apparaîtront pas dans la liste des fichiers non suivis. C'est ta première vérification que le filtre fonctionne.

  5. Renommer la branche par défaut master en main

    Sur les versions un peu anciennes de Git, git init crée une branche master. La convention GitHub depuis 2020 est main. Le faire avant le premier commit évite tout renommage post-push.

    bash 
    git branch -m master main
git branch --show-current  # doit afficher : main

    Pour ne plus avoir à le faire dans tes futurs projets :

    bash 
    git config --global init.defaultBranch main

  6. Indexer les fichiers (git add) et vérifier

    bash 
    git add .
git status

    git add . place tous les fichiers non ignorés dans la zone d'index (staging area). git status liste alors les fichiers prêts à être commités.

    Le réflexe anti-fuite

    Avant chaque commit, lis la liste de git status. Aucun .env, aucun fichier de credentials, aucun dossier de config personnelle ne doit s'y trouver. Si oui : git rm --cached <fichier> et corrige le .gitignore.

  7. Configurer ton identité Git pour ce projet

    Git refuse de créer un commit s'il ne sait pas qui tu es. Tu peux configurer l'identité au niveau global (tous tes projets) ou local (uniquement ce dépôt).

    bash 
    # Local : config limitée à ce dépôt
git config --local user.name "<ton-pseudo>"
git config --local user.email "<ton-email>"

# Ou global : config partagée par tous tes dépôts
git config --global user.name "<ton-pseudo>"
git config --global user.email "<ton-email>"
    Email "noreply" GitHub

    Pour ne pas exposer ton vrai e-mail dans les commits publics, GitHub fournit un alias du type <id>+<ton-pseudo>@users.noreply.github.com (Settings → Emails → Keep my email addresses private). Les commits restent liés à ton profil GitHub mais ton email réel reste privé.

  8. Faire le premier commit

    bash 
    git commit -m "Initial commit"
git log --oneline

    git log --oneline doit te montrer une ligne avec le hash court du commit et son message. À ce stade, tout est versionné en local, rien n'est encore en ligne.

  9. Créer le dépôt distant sur GitHub

    1. Va sur github.com/new.
    2. Nom : <mon-projet> (idéalement le même que ton dossier local).
    3. Description : optionnelle.
    4. Visibilité : Public ou Private.
    5. Ne coche RIEN dans "Initialize this repository with…" (pas de README, pas de .gitignore, pas de license).
    6. Crée le dépôt.
    Pourquoi un dépôt distant vide

    Si GitHub crée automatiquement un README ou un .gitignore côté distant, ton historique local et l'historique distant seront divergents dès le départ, et ton premier push sera rejeté. En partant d'un dépôt distant vide, tu pousses simplement ton historique local tel quel.

  10. Connecter le local au distant et pousser

    Ajoute l'URL du dépôt distant comme remote nommé origin :

    bash 
    git remote add origin https://github.com/<ton-pseudo>/<mon-projet>.git
git remote -v   # vérifie l'URL fetch + push
git push -u origin main

    Le flag -u (set upstream) lie ta branche locale main à la distante origin/main. À partir de là, un simple git push ou git pull saura quoi faire sans répéter les arguments.

  11. S'authentifier sans retaper le mot de passe à chaque push

    Au moment du push, GitHub te demande de t'authentifier. Le mot de passe classique n'est plus accepté depuis 2021. Plusieurs options :

    1. OAuth via Git Credential Manager (GCM) — si GCM est installé sur ta machine (souvent le cas sur Windows et macOS modernes), une fenêtre de navigateur s'ouvre automatiquement pour t'authentifier sur GitHub. Le credential est ensuite stocké et réutilisé pour les pushes suivants. Le plus simple si disponible.
    2. Personal Access Token (PAT) "fine-grained" — un token limité à un seul dépôt et à des permissions précises. Tu le crées sur github.com/settings/personal-access-tokens/new, tu sélectionnes Only select repositories → <mon-projet>, et tu donnes la permission Contents: Read and write. Quand Git demande le mot de passe, tu colles le token. Pour qu'il soit mémorisé localement (au repo seulement) :
      bash 
      git config --local credential.helper 'store --file=.git/.git-credentials'
      Le fichier .git/.git-credentials reste dans .git/, qui n'est jamais poussé.
    3. Clé SSH — couvert dans la fiche GitHub. Plus pérenne, pas de token en clair, idéal une fois maîtrisé.
    PAT en clair

    Le credential helper store écrit ton token en clair dans le fichier. Sur un poste partagé ou sensible, préfère SSH ou GCM. Sur ton poste perso, c'est acceptable si le fichier reste protégé (permissions 600 par défaut).

  12. Bonus : activer GitHub Pages pour publier le site

    Si ton projet est un site statique HTML/CSS/JS, GitHub peut l'héberger gratuitement.

    1. Sur la page du dépôt : Settings → Pages.
    2. Source : Deploy from a branch.
    3. Branch : main, dossier : / (root).
    4. Save.
    5. Attends 1 à 2 minutes : l'URL https://<ton-pseudo>.github.io/<mon-projet>/ devient active.
    Repo public ou privé ?

    GitHub Pages depuis un repo privé nécessite un compte payant. Mais pour un site statique, garder le repo en privé n'a qu'un intérêt limité : tout le code servi au navigateur est de toute façon visible (clic droit → Afficher le source). La mise en privé ne cache que l'historique, les drafts en branches et les fichiers non servis. Pour la plupart des cas pédagogiques, public + Pages est le plus simple.

Workflow quotidien après publication

Une fois le projet en ligne, chaque modification se résume à ce cycle :

bash 
git status                        # voir ce qui a changé
git add <fichier>                  # ou : git add .
git commit -m "docs: ajout lien live"
git push                          # plus besoin de -u

Les messages de commit gagnent à suivre une convention type type: description (ex. feat:, fix:, docs:, refactor:). Cohérent, lisible, et facilement exploitable par des outils plus tard.

Aide-mémoire

bash 
# Initialisation
git init
git branch -m master main
git add .
git status
git commit -m "Initial commit"

# Identité (local au repo)
git config --local user.name "<ton-pseudo>"
git config --local user.email "<ton-email>"

# Connexion au distant
git remote add origin https://github.com/<ton-pseudo>/<mon-projet>.git
git remote -v
git push -u origin main

# Stockage du PAT local au repo
git config --local credential.helper 'store --file=.git/.git-credentials'

# Cycle quotidien
git status
git add .
git commit -m "message"
git push

# Vérifier l'état distant
git log --oneline
git ls-remote origin

Pour aller plus loin