Auto-déployer GitHub Pages sur push main

Contexte

GitHub Pages héberge automatiquement un site statique généré depuis un repository. Pour ulk, le site doc (Astro) se redéploie automatiquement à chaque push sur main via un workflow GitHub Actions. Aucune configuration manuelle après setup initial.

Prérequis

• Repository GitHub public (ou Pages activé)
• Site Astro ou framework statique dans site/
• .github/workflows/ accessible en écriture

Étapes

1. Activer GitHub Pages dans les Settings du repo

Settings → Pages
Source: Deploy from a branch
Branch: gh-pages (créée auto par le workflow)
Folder: / (root)

2. Créer le workflow GitHub Actions

Créer .github/workflows/deploy.yml :

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
    paths:
      - 'site/**'

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm ci
        working-directory: site
      
      - name: Build Astro site
        run: npm run build
        working-directory: site
      
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site/dist

3. Pousser le workflow

git add .github/workflows/deploy.yml
git commit -m "ci: add github pages deployment"
git push origin main

4. Vérifier le déploiement

# Actions tab dans le repo
# Voir le workflow tourner en temps réel
# Une fois complet → site accessible

# Ou via CLI
gh run list --repo user/repo
gh run view <run-id> --log

Accéder au site déployé

https://user.github.io/ulk/

(Remplacer user et ulk par ton username et repo)

Configurer le domaine custom (optionnel)

Settings → Pages
Custom domain: docs.mycompany.com
→ Crée CNAME auto

Puis dans le repo, ajouter CNAME à la racine :

user.github.io

Ou via le workflow automatiquement.

Workflow variables

# Notifier Slack après déploiement (optionnel)
- name: Notify Slack
  if: always()
  run: |
    curl -X POST ${{ secrets.SLACK_WEBHOOK }} \
      -H 'Content-Type: application/json' \
      -d "{\"text\": \"Site déployé sur GitHub Pages ✓\"}"

Troubleshooting

Symptôme	Cause probable	Résolution
Workflow échoue	Dépendances manquantes	Vérifier npm ci dans site/
Site blank	Mauvais publish_dir	Adapter ./site/dist si nécessaire
404 sur domaine	CNAME non configuré	Ajouter CNAME dans Settings → Pages
Ancien contenu en cache	Cache du browser	CTRL+SHIFT+R pour hard refresh

Variantes

• Deploy uniquement si tests passent : Ajouter npm run test avant build
• Deploy depuis une autre branche : Remplacer main par deploy dans le workflow
• Notifications Slack : Envoyer message après déploiement réussi

Voir aussi

• site/ — Source du site Astro
• .github/workflows/ — Autres workflows (lint, tests)
• 30-vercel-deploy.md — Déployer l’app (pas la doc)