Aller au contenu principal

Documentation dans un repo séparé (auto-sync)

Ce guide permet de garder la documentation dans ce projet, tout en la publiant automatiquement dans un dépôt dédié docs.

Principe​

  • Source de vérité: dossier docs/ dans ce repo.
  • Réplication automatique: GitHub Action vers un repo docs séparé.
  • Déclenchement: à chaque push sur main/master avec changements dans docs/.
  • Mode safe-sync: publication dans un sous-dossier du repo cible (par défaut docs/), sans écraser la racine.

Cible actuelle​

  • Repo docs séparé: https://github.com/ismaelgansonre/ABC-docs.git
  • Branche docs: main

Fichier déjà prêt​

Workflow ajouté:

  • .github/workflows/sync-docs-to-separate-repo.yml

Étapes à faire (GitHub)​

1) Créer le repo docs​

Exemple: your-org/abc-docs

Statut actuel: ✅ déjà fait (ismaelgansonre/ABC-docs).

2) Ajouter les secrets dans le repo principal​

Dans Settings > Secrets and variables > Actions:

  • DOCS_REPO_URL = URL HTTPS du repo docs
    • exemple: https://github.com/your-org/abc-docs.git
  • DOCS_REPO_TOKEN = token GitHub (PAT) avec droit repo (write)
  • DOCS_TARGET_BRANCH (optionnel) = branche cible (par défaut main)
  • DOCS_TARGET_SUBDIR (optionnel) = sous-dossier cible (par défaut docs)

Valeurs recommandées pour ce projet:

  • DOCS_REPO_URL=https://github.com/ismaelgansonre/ABC-docs.git
  • DOCS_TARGET_BRANCH=main
  • DOCS_TARGET_SUBDIR=docs

3) Tester​

  • Modifier un fichier dans docs/
  • Push sur main
  • Vérifier le job Sync docs to separate repository
  • Vérifier le repo docs: contenu mis à jour

Notes de sécurité​

  • Utiliser un token dédié docs-bot, permissions minimales.
  • Rotation régulière du token.

Important (mode propre monorepo)​

  • Ne pas garder docs/.git dans le monorepo (repo imbriqué).
  • Mode recommandé: source unique dans ce monorepo + sync GitHub Action vers ABC-docs.
  • Le workflow met à jour uniquement ABC-docs/docs/ (ou le sous-dossier défini), et préserve les autres fichiers du repo cible.

Option Cloudflare Pages​

Une fois le repo docs alimenté, connecte ce repo à Cloudflare Pages pour héberger la documentation en auto-deploy.

Variante “source de vérité inversée”​

Si tu préfères que la source de vérité soit le repo docs, on peut faire l’inverse (pull/submodule/subtree), mais ce setup est généralement plus complexe pour l’équipe produit.