Corpus refresh — synchronisation telaria-doc → RAG

Contexte

Le RAG de telaria.dev indexe docs/ : un clone git de telaria-doc hébergé sur le VPS (/var/www/telaria/docs). Sans mécanisme de refresh, ce clone devient stale dès qu'un nouveau commit est poussé sur telaria-doc.

Architecture

Deux mécanismes complémentaires :

Les deux passent par le même pipeline :

Webhook / BO → BackgroundCorpusCheckoutLauncher
    → CLI détaché : app:docs:checkout --ref=<ref>
        → CorpusManager::checkout(ref)
            → git fetch origin --tags --prune
            → git checkout <ref>
            → git pull --ff-only (si branche, pas si tag/SHA détaché)
        → IngestionService::ingest() (drop + rebuild full)
        → AppSettings: RUNNING=false, LAST_AT=now, CURRENT_REF=ref

Webhook GitHub

Endpoint : POST https://telaria.dev/api/webhook/github/docs

Sécurité : HMAC-SHA256 du corps de la requête, validé via X-Hub-Signature-256.

• Secret : variable d'environnement GITHUB_WEBHOOK_SECRET (.env.local sur le serveur).
• Si secret vide ou signature invalide → 401.

Filtre : seuls les événements create avec ref_type: tag sont traités. Push de branches, PRs, etc. → réponse 200 "Ignoré".

Comportement : si un checkout est déjà en cours (docs.checkout_running=true), le webhook répond 202 sans relancer.

Configuration webhook GitHub (sur telaria-doc) :

Note : GITHUB_WEBHOOK_SECRET doit être ajouté au vault Ansible (group_vars/production.yml) pour être injecté dans .env.local via le rôle symfony.

Section BO — « Corpus (source) »

Route : /admin/config/corpus
Catégorie IA, priorité 14 (juste avant « Documentation (RAG) » → 15).

Flux d'utilisation

1. Admin choisit une branche (liste issue de git branch -r local — branches remote-tracking).
2. Admin clique ↻ Rafraîchir (optionnel) : déclenche un git fetch via sudo -u ubuntu, puis recharge le select ref.
3. Le select ref se peuple via AJAX (GET /admin/corpus/refs?branch=<b>) depuis les refs locales :
   • Tags fusionnés dans la branche (du plus récent, en gras dans le select).
   • 10 derniers commits (SHA court — date — message).
4. Admin sélectionne le ref et soumet.
5. Checkout + ré-indexation se lancent en fond (process CLI détaché via sudo -u ubuntu).
6. La section affiche le verrou « en cours » + auto-refresh (via data-config-reindex-running).

Endpoints AJAX

Infrastructure VPS

Ségrégation d'identité

www-data (FPM) n'a aucune clé SSH et aucune identité externe. C'est ubuntu qui détient la clé SSH GitHub. La communication entre les deux passe par des règles sudoers ultra-scoped.

git safe.directory

Sans cette config, FPM reçoit fatal: detected dubious ownership en lisant un dépôt appartenant à ubuntu.

# tlr-ansible roles/system/tasks/main.yml
- name: Autoriser git sur /var/www (safe.directory système)
  community.general.git_config:
    name: safe.directory
    value: /var/www/telaria/docs
    scope: system

Wrapper /usr/local/bin/telaria-docs-checkout

Les noms de commandes Symfony contiennent des : — caractère réservé en syntaxe sudoers. Le wrapper contourne cette limitation.

#!/bin/bash
exec /usr/bin/php /var/www/telaria/bin/console app:docs:checkout "$@"

Règle sudoers scoped

www-data ALL=(ubuntu) NOPASSWD: /usr/bin/git -C /var/www/telaria/docs fetch origin --tags --prune
www-data ALL=(ubuntu) NOPASSWD: /usr/local/bin/telaria-docs-checkout *

Ces deux règles couvrent exactement : le bouton ↻ Rafraîchir (fetch) et le checkout en fond. Rien d'autre.

Composants

tlr-codexia

AppSettings keys :

telaria-app

DocsLibrary — mode default-allow

DocsLibrary (et le RAG via excluded_paths) opèrent en default-allow : tout fichier .md est visible sauf exclusions permanentes codées dans le bundle :

Pas d'allowlist à maintenir dans services.yaml. Si un dossier doit être exclu, ajouter son segment à ALWAYS_EXCLUDED_SEGMENTS dans DocsLibrary. Si un dossier doit être visible : il l'est d'office, sans intervention.

Opérations

Provisionnement initial du clone docs/

Si docs/ n'existe pas encore sur le VPS :

cd /var/www/telaria
git clone git@github.com:<owner>/telaria-doc.git docs
cd docs && git checkout master

Le webhook s'occupera ensuite des mises à jour automatiques.

Vérifier l'état courant

# Via BO : /admin/config/corpus (carte "État courant")
# Via CLI :
ssh -p 9501 ubuntu@telaria.dev "cd /var/www/telaria/docs && git log --oneline -3 && git describe --tags"

Forcer un refresh manuel en SSH

ssh -p 9501 ubuntu@telaria.dev \
  "cd /var/www/telaria && php bin/console app:docs:checkout --ref=master --env=prod"

Logs checkout

tail -f /var/www/telaria/var/log/corpus-checkout.log

Workflow de release recommandé

1. Pousser les commits sur telaria-doc/develop
2. Merger develop → master
3. Tagger : git tag 0.9.0 && git push --tags
→ Webhook déclenche automatiquement checkout 0.9.0 + ré-indexation
→ telaria.dev reflète la doc de release en quelques minutes

Voir aussi

• bundles/tlr-rag.md — pipeline RAG complet
• ../03-comment-je-travaille/guides/runbook.md — runbook VPS complet

Implémentation

Historique des décisions