Repository Maintainer
Flux de travail systématique pour transformer des profils GitHub fragmentés en dépôts propres, maintenables et professionnels.
Aperçu
Exécutez le nettoyage en 6 phases. Ignorez les phases non pertinentes. Obtenez toujours la confirmation de l'utilisateur pour les actions destructrices (suppression, renommage, fusion).
Principes fondamentaux (non négociables)
Chaque dépôt — nouveau ou ancien, actif ou archivé — doit posséder ces quatre documents de base. Ne considérez pas un nettoyage comme terminé tant que les quatre ne sont pas vérifiés.
| Document | Règle | Pourquoi |
|---|---|---|
| LICENSE | Chaque dépôt public obtient une LICENSE. Par défaut MIT sauf indication contraire de l'utilisateur. | Sans licence, le code est « tous droits réservés » par défaut. Personne ne peut légalement l'utiliser. |
| README.md | Doit exister avec au moins : nom du projet, description en une phrase, et instructions d'utilisation/installation si applicable. | La première chose que chaque visiteur voit. Un README vide ou manquant signale un abandon. |
| .gitignore | Doit correspondre au langage principal (Python/PHP/Node/etc.). Ne commitez jamais les artefacts de build, le cache, les fichiers d'environnement ou les configurations IDE. | Empêche la fuite accidentelle de secrets et maintient la lisibilité des diffs. |
| Description GitHub | Le champ description ne doit jamais être vide. Une phrase, en anglais simple (ou dans la langue du dépôt). | Apparaît dans les résultats de recherche, les épingles de profil et les cartes sociales. |
Si un dépôt manque de l'un des quatre, sa correction a priorité sur la fusion, le renommage ou le refactoring.
Phase 1 : Analyse et diagnostic
Récupérez la liste complète des dépôts via l'API GitHub :
curl -sH "Authorization: Bearer TOKEN" \
"https://api.github.com/user/repos?per_page=100&affiliation=owner"
Vérifiez pour chaque dépôt :
- Absence de
LICENSE,.gitignore,README.md - Champ
descriptionvide - Incohérences de nommage (majuscules/minuscules mélangées, noms trop longs)
- Doublons ou séries évidents (ex.
project,project-v2,project-mineru) - Noms contenant
outdated,deprecated,old,test
Phase 2 : Standardiser les fichiers fondamentaux
Pour chaque dépôt actif, assurez-vous que l'ensemble de fichiers minimum existe :
| Fichier | Règle |
|---|---|
LICENSE | Par défaut MIT sauf indication contraire de l'utilisateur |
.gitignore | Correspond au langage principal (Python/PHP/Node) |
README.md | Doit exister ; réécrire s'il n'est qu'un espace réservé |
| Description GitHub | Résumé en une phrase via l'API |
Mise à jour groupée via l'API GitHub Contents (PUT /repos/{owner}/{repo}/contents/{path}).
Critique : les here-strings PowerShell corrompent les blocs de code à triple backtick en Markdown. Utilisez des scripts Python pour la génération groupée de README afin d'éviter les échecs d'échappement ` → ```.
Phase 3 : Gérer les dépôts obsolètes
Arbre de décision :
| Condition | Action |
|---|---|
Le nom contient outdated / deprecated / old | Archiver ou supprimer |
| Remplacé par un dépôt plus récent | Archiver + lien vers le successeur dans le README |
| L'historique du dépôt public contient des secrets divulgués (clés API) | Supprimer (l'archive laisse l'historique intact) |
| Le dépôt privé contient des clés, mots de passe, configuration privée ou données personnelles | L'utilisateur peut ignorer les règles de fuite ; traiter comme un état privé acceptable sauf s'il demande un assainissement |
| Utile comme référence mais non maintenu | Archiver |
Les dépôts archivés sont en lecture seule. Pour modifier un dépôt archivé (renommer, mettre à jour le README), désarchivez d'abord (PATCH {"archived": false}), effectuez les modifications, puis réarchivez.
Phase 4 : Fusionner les dépôts connexes
Lorsque 2+ dépôts sont des variantes du même système (backends, moteurs, adaptateurs différents) :
Option A — Monorepo (recommandé)
Créez un nouveau dépôt propre (sans historique). Placez chaque variante dans un sous-répertoire engines/{nom}/.
project-suite/
├── main.py # moteur par défaut
├── engines/
│ ├── babeldoc/
│ └── mineru/
└── README.md
Préservez le point d'entrée et la configuration de chaque moteur. Mettez à jour le README racine pour expliquer le changement.
Option B — Sous-module Git Gardez les dépôts indépendants. Ajoutez des sous-modules dans le dépôt parent. À utiliser lorsque la préservation de l'historique est plus importante que la simplicité.
Option C — Garder indépendant + Lien Ne fusionnez pas. Ajoutez des liens croisés dans les README. À utiliser lorsque les variantes ont considérablement divergé.
Si l'historique contient des secrets : Créez toujours un nouveau dépôt propre et copiez l'instantané actuel (via téléchargement zip + re-commit). N'utilisez pas git merge ou git submodule car les fuites d'historique persisteraient.
Phase 5 : Renommer les dépôts
API PATCH : PATCH /repos/{owner}/{repo} avec {"name": "new-name"}.
Directives :
- Tout en minuscules, tirets uniquement
- 3-4 mots maximum
- Supprimez les mots redondants (
based-on,design-and-development) - Ajoutez le suffixe
outdatedaux dépôts archivés s'il n'est pas déjà présent
GitHub redirige automatiquement les anciennes URL pendant une période, mais les signets et les scripts peuvent se casser. Confirmez avec l'utilisateur avant de renommer les dépôts avec des étoiles ou des forks.
Phase 6 : Refactoring au niveau du code
Une fois la structure distante propre, refactorez le code dans les dépôts :
- Terminologie unifiée — Remplacez les noms de marque codés en dur par des termes génériques (
GPTProcessor→LLMProcessor) tout en préservant les ID de modèle API réels (gpt-4,gpt-5). - Renommage de fichiers — L'API GitHub Contents n'a pas de renommage ; créez un nouveau fichier avec le contenu mis à jour, supprimez l'ancien fichier.
- Réorganisation des répertoires — Utilisez les modèles
engines/,variants/, oucore/+adapters/pour les projets multi-variantes.
Pousser les refactorisations locales volumineuses vers le dépôt distant
Lorsque l'utilisateur télécharge du code localement, effectue des modifications importantes (renommages de fichiers, renommages de variables, réécritures structurelles) et doit pousser vers le dépôt distant.
Analyse de sécurité pré-push (OBLIGATOIRE)
Avant de pousser, vous devez d'abord analyser les fuites de secrets. Signalez immédiatement toute découverte et interrompez le push.
Exception pour les dépôts privés : Si le dépôt cible est confirmé privé, vous pouvez ignorer les règles de fuite de clés, mots de passe, configuration privée, données personnelles et autres informations sensibles. L'analyse peut servir d'avertissement, mais les correspondances ne bloquent pas le push, ne nécessitent pas la suppression et la reconstruction du dépôt, ni le remplacement par des variables d'environnement, sauf si l'utilisateur demande explicitement un nettoyage ou prévoit de rendre le dépôt public.
Mode d'analyse (les deux doivent être exécutés — exécuter uniquement l'expression régulière de token peut manquer les mots de passe en clair) :
① Token à haute entropie / clé API :
grep -rn "sk-[A-Za-z0-9]\{20,\}\|ghp_[A-Za-z0-9]\{36\}\|ghu_\|github_pat_\|Bearer [A-Za-z0-9+/=]\{40,\}" \
--include="*.py" --include="*.js" --include="*.ts" --include="*.yaml" \
--include="*.env" --include="*.json" --include="*.bat" --include="*.sh" \
--exclude-dir=".git" .
② Mot de passe en clair / auxiliaire d'authentification (que l'expression régulière de token ne peut pas attraper ; en pratique, une ligne echo "<mot_de_passe_sudo>" dans askpass.sh a déjà été oubliée et poussée sur GitHub avec le commit init) :
git ls-files -z | xargs -0 grep -nIE "password|passwd|mot de passe|SUDO_ASKPASS|sshpass|^[[:space:]]*echo[[:space:]]+[\"'][^\"']{6,}[\"']" 2>/dev/null \
| grep -vE "\.md:|getenv|getpass|placeholder|example"
# Et vérifiez manuellement les fichiers isolés askpass.sh / *_secret* / .pgpass / .npmrc — ces fichiers entiers sont des identifiants.
Pour un dépôt public, toute correspondance dans l'une ou l'autre analyse déclenche le processus obligatoire ci-dessous. Pour un dépôt privé, les correspondances ne font qu'avertir l'utilisateur et ne constituent pas un blocage. Notez que l'analyse porte sur git ls-files (fichiers suivis) ; ce qui est ignoré par .gitignore n'est pas considéré comme une fuite, mais les fichiers déjà commités, même s'ils sont maintenant dans .gitignore, sont toujours dans l'historique.
Format du rapport :
[LEAK] scripts/eval.py:15 — sk-xxxx (valeur de repli codée en dur)
[LEAK] ui/ui_backend.py:33 — sk-xxxx (valeur par défaut codée en dur)
Processus obligatoire après une fuite détectée :
- Informez immédiatement l'utilisateur du fichier et de la ligne concernés
- Remplacez par une variable d'environnement (
os.getenv("API_KEY")sans valeur par défaut) - Si déjà poussé vers le dépôt distant : informez l'utilisateur et, après confirmation explicite, supprimez et recréez le dépôt (l'historique Git ne peut pas être complètement effacé par un force push)
- L'utilisateur révoque la clé auprès du fournisseur de services correspondant
Liste de vérification pré-push
À exécuter avant chaque push :
git status
Confirmez l'absence de :
- Fichiers non suivis (untracked files) — nouveaux fichiers non suivis (oublis courants : docs/, scripts/, modèles de config)
- Modifications non indexées (changes not staged) — modifications non ajoutées
- Modifications à commiter (changes to be committed) contenant des fichiers qui ne devraient pas être téléchargés (clés, données personnelles, scripts temporaires)
Avant confirmation, le push direct est interdit.
Arbre de décision
| Situation | Action recommandée |
|---|---|
Le dépôt local n'a pas de dossier .git (zip téléchargé / fichiers copiés) | Voir Scénario A ci-dessous |
Le dépôt local est un git clone avec historique, dépôt distant inchangé | git add → commit → push normal |
Le dépôt local est un git clone, le dépôt distant a de nouveaux commits | git pull --rebase ou merge, résoudre les conflits, push |
Le dépôt local est un git clone, les modifications sont des renommages + réécritures massives | Voir Scénario B ci-dessous |
| Vous voulez préserver l'historique distant mais remplacer tout le code | Voir Scénario C ci-dessous |
Scénario A : Le dépôt local n'a pas d'historique Git
Cas le plus courant : l'utilisateur télécharge un zip, édite abondamment, puis veut synchroniser.
Option A1 — Force Push (Projets personnels / solo)
# Dans le dossier du projet local
git init
git add .
git commit -m "refactor: réécriture majeure"
git remote add origin https://github.com/OWNER/REPO.git
git branch -M main
git push -u origin main --force
⚠️ Détruit l'historique distant. À utiliser uniquement si l'utilisateur confirme que l'historique distant est jetable.
Option A2 — Préserver l'historique distant (recommandé pour les dépôts de valeur)
git clone https://github.com/OWNER/REPO.git temp-repo
cp -r temp-repo/.git ./your-local-project/
cd your-local-project
git add .
git commit -m "refactor: réécriture majeure"
git push
Cela conserve tous les commits précédents et ajoute le refactoring comme un seul nouveau commit.
Option A3 — Nouveau dépôt propre Si la réécriture est si radicale qu'il s'agit essentiellement d'un nouveau projet :
- Créez un nouveau dépôt sur GitHub (incluez
descriptiondans le corps de la création ou utilisez PATCH immédiatement après) - Poussez le code local vers ce nouveau dépôt
- Archivez l'ancien dépôt avec un lien vers le successeur dans le README
Scénario B : Renommages massifs + réécritures dans un dépôt cloné
Règle critique : ne mélangez jamais les renommages de fichiers et les modifications de contenu dans le même commit. Git traitera cela comme « supprimer l'ancien fichier + créer un nouveau fichier » et perdra le lien d'historique.
Stratégie de commit par étapes :
# Étape 1 : Renommer uniquement
git mv old_module.py new_module.py
git mv old_utils/ new_utils/
git commit -m "refactor: renommer les modules"
# Étape 2 : Renommages de variables/classes
git add .
git commit -m "refactor: renommer les variables et classes"
# Étape 3 : Modifications logiques
git add .
git commit -m "feat: mettre à jour la logique principale"
Si l'utilisateur a déjà tout mélangé dans l'arbre de travail :
# Stasher les modifications actuelles, rejouer par étapes
git stash push -m "refactoring mixte"
# Restaurer les renommages uniquement (utiliser git mv ou mv manuel + git add)
git mv old_file new_file
git commit -m "refactor: renommer les fichiers"
# Restaurer les modifications de contenu
git stash pop
# Résoudre les conflits si nécessaire, puis commit
Scénario C : Remplacer tout le code tout en conservant l'historique
Utile lorsque l'utilisateur veut repartir d'un code propre mais conserver les étoiles, les issues et l'URL.
git checkout --orphan fresh-start
git rm -rf .
# Copier le nouveau code local ici
git add .
git commit -m "init: réécriture propre"
git branch -D main
git branch -m main
git push -u origin main --force
Vérification de la détection de renommage
Après le push, vérifiez que Git a correctement suivi les renommages :
git log --follow -- new_file.py
Si l'historique est cassé (montre le fichier comme tout nouveau), le renommage et la modification de contenu ont été commités ensemble.
Sécurité et conformité
- Token GitHub : Si un PAT est nécessaire, cherchez dans la mémoire de l'agent (n'écrivez pas de chemin/compte/valeur spécifique ici). N'écrivez JAMAIS la valeur du token dans un fichier qui sera poussé (y compris ce skill, README, configuration) — tout contenu contenant un token sera révoqué par le secret-scanning de GitHub dès qu'il sera poussé.
- Hygiène du token : Après les opérations groupées, demandez à l'utilisateur de révoquer immédiatement le PAT sur
https://github.com/settings/tokens. - Exception pour les dépôts privés : Si un dépôt est privé, l'agent peut ignorer les règles de fuite de clés, mots de passe, configuration privée, données personnelles et autres informations sensibles. Ne bloquez pas le push, n'exigez pas d'assainissement et ne recommandez pas la suppression uniquement parce que l'historique privé contient des secrets, sauf si l'utilisateur le demande ou si le dépôt pourrait devenir public.
- Historique public contenant des secrets : Si un dépôt public a déjà commité des clés API, la suppression du dépôt est le seul moyen de purger l'historique de GitHub. Un force push avec un historique assaini ne garantit pas la suppression des systèmes de sauvegarde de GitHub.
- Dépôts publics archivés avec secrets : Si la suppression est inacceptable, au minimum retirez le dépôt de la visibilité publique (rendez-le privé) ou supprimez-le et recréez-le vide avec un code propre.
Référence technique
Pièges d'encodage (Windows)
PowerShell utilise par défaut CP1252 pour stdout, ce qui détruit les caractères chinois et les blocs de code Markdown. Reconfigurez toujours :
import sys
sys.stdout.reconfigure(encoding='utf-8')
Lorsque vous utilisez Invoke-RestMethod dans PowerShell avec des corps JSON contenant des backticks ou des triples backticks, privilégiez les scripts Python pour la génération de contenu afin d'éviter que la sérialisation JSON ne transforme ``` en `.
Modèles d'API GitHub
Créer un dépôt (n'omettez jamais description) :
api_call("POST", "/user/repos", {
"name": "repo-name",
"private": True,
"description": "Résumé en une phrase."
})
Créer/mettre à jour un fichier :
import base64, json, urllib.request
payload = {
"message": "message du commit",
"content": base64.b64encode(content.encode('utf-8')).decode(),
"sha": existing_sha # requis pour les mises à jour
}
req = urllib.request.Request(
f"https://api.github.com/repos/{owner}/{repo}/contents/{path}",
method="PUT",
data=json.dumps(payload).encode(),
headers={"Authorization": f"Bearer {token}", ...}
)
Archiver/désarchiver :
api_call("PATCH", f"/repos/{owner}/{repo}", {"archived": True})
Renommer un dépôt :
api_call("PATCH", f"/repos/{owner}/{repo}", {"name": "new-name"})
Supprimer un dépôt :
api_call("DELETE", f"/repos/{owner}/{repo}")
Téléchargement groupé sans clone
Téléchargez un instantané du dépôt sous forme de zip pour éviter un git clone lent sur des réseaux instables :
curl -sL "https://github.com/{owner}/{repo}/archive/refs/heads/main.zip" -o {repo}.zip
Ressources fournies
scripts/repo_analyzer.py— Analyse les dépôts GitHub de l'utilisateur et génère des recommandations de nettoyagescripts/bulk_file_updater.py— Crée/met à jour en masse LICENSE, .gitignore, README via l'API GitHub