Checklist de transfert du code source pour clients et agences

Ce que doit accomplir un transfert de code source

Un transfert de code source est le moment où le projet cesse d’être « quelque chose que l’agence peut faire fonctionner » pour devenir « quelque chose que le client peut posséder ». Sans un transfert clair, des problèmes courants apparaissent vite : l’app ne se compile que sur un seul ordinateur, la production dépend d’un secret introuvable, ou une petite mise à jour se transforme en jours de recherches.

L’objectif de toute checklist de transfert est simple : après le transfert, le client peut compiler, exécuter et déployer le produit sans devoir appeler l’agence. Cela ne veut pas dire « plus jamais d’assistance ». Cela signifie que les bases sont reproductibles et documentées, pour que la prochaine personne puisse prendre le relais en confiance.

Ce qui compte comme livrables doit être explicite. Au minimum, un transfert complet comprend généralement :

• Le dépôt complet (y compris les fichiers de déploiement et les scripts de migration)
• Des docs d'installation fonctionnant sur une machine propre
• La transmission des accès (comptes, permissions et emplacement du système)
• Un runbook pour les tâches courantes (déploiement, rollback, sauvegardes, logs)
• Un tag ou snapshot final « connu comme bon » que le client peut citer

Le périmètre importe autant que le contenu. Certains transferts couvrent un seul environnement (par exemple, la production). D'autres incluent dev, staging et production avec des paramètres et processus séparés. Si vous ne précisez pas les environnements inclus, chacun supposera quelque chose de différent, et c’est là que surviennent les indisponibilités.

Une manière concrète de définir le succès est un test de vérification : une personne qui n’a pas construit l’app doit pouvoir exporter le code (par exemple depuis une plateforme comme Koder.ai), suivre la doc, définir les variables d’environnement, exécuter les migrations, construire et déployer dans l’environnement convenu.

Cette checklist se concentre sur la préparation technique : variables d’environnement, rotation des secrets, migrations de base de données, scripts de déploiement et vérification des builds. Elle ne couvre pas les aspects juridiques, contrats, clauses IP ou litiges de paiement. Ceux-ci sont importants aussi, mais appartiennent à un accord séparé.

Avant l’export : s’accorder sur la propriété et le calendrier

Un transfert propre commence avant tout export. Si vous vous mettez d’accord sur qui possède quoi et quand, vous évitez les surprises de dernière minute comme des déploiements cassés, un hébergement impayé ou des accès manquants.

Fixer la date de transfert et une courte fenêtre de gel

Choisissez une date de transfert et définissez une fenêtre de gel (souvent 24–72 heures) où seules les corrections urgentes sont acceptées. Cela permet de garder le code exporté et le système en service synchronisés. Si un correctif est nécessaire pendant le gel, notez exactement ce qui a changé et assurez-vous qu’il soit inclus dans l’export final.

Clarifier la propriété des comptes et la facturation

Décidez qui possèdera le DNS, l’hébergement cloud et les services payants après le transfert. Ce n’est pas que de la paperasse. Si la facturation reste sur la carte de l’agence, des services peuvent être suspendus sans prévenir.

Une façon rapide de rendre cela concret :

• Nommez le propriétaire du compte pour le DNS, l’hébergement et les e-mails
• Confirmez qui paie chaque facture à partir de la date de transfert
• Décidez si les comptes sont transférés ou recréés sous le client
• Enregistrez le contact support pour chaque fournisseur

Écrivez cela en langage clair pour que les deux parties puissent le suivre.

Lister les environnements et où ils s’exécutent

Mettez-vous d’accord sur les environnements existants (local, staging, production) et où chacun s’exécute. Précisez si la staging est un serveur séparé, une base de données distincte, ou simplement un flag feature. Si vous avez utilisé une plateforme comme Koder.ai, confirmez aussi ce qui est hébergé là-bas versus ce qui doit tourner sur l’infrastructure du client après l’export.

Rassembler les accès en amont

Ne laissez pas la demande d’accès au dernier jour. Assurez-vous que les bonnes personnes peuvent atteindre ce dont elles ont besoin : le dépôt, le CI, l’hébergement, la base de données et le fournisseur d’e-mails.

Concluez aussi le test d’acceptation final et le processus de validation. Par exemple : « Le client peut construire depuis une machine propre, exécuter les migrations, déployer en staging et passer le test de fumée. Ensuite, les deux parties signent la validation par écrit. »

Bases du dépôt et de la documentation à inclure

Une bonne checklist commence par un dépôt qu’une nouvelle équipe peut ouvrir et comprendre en quelques minutes. Confirmez ce qui est inclus (code app, templates de config, scripts) et ce qui est volontairement exclu (secrets réels, clés privées, fichiers volumineux générés). Si quelque chose est exclu, indiquez où il se trouve et qui en est propriétaire.

Gardez la structure prévisible. Visez des dossiers de haut niveau clairs comme frontend/, backend/, mobile/, infra/, scripts/, et docs/. Si le projet est un monorepo, expliquez comment les parties s’articulent et comment exécuter chacune d’elles.

Votre README doit être utilisable par quelqu’un qui n’a pas créé le projet. Il doit couvrir les prérequis et le chemin le plus rapide vers une exécution dev fonctionnelle, sans supposition.

Que documenter (minimum)

Incluez une courte section README répondant à :

• Ce que contient ce dépôt et ce qu’il fait (un paragraphe)
• Les prérequis avec les versions exactes (runtime, gestionnaire de paquets, Docker si nécessaire)
• Les étapes « une commande » pour démarrer en local (et ce qu’est le « succès »)
• Comment exécuter les tests et construire un artefact de production
• Où trouver les docs clés : notes d’architecture, migrations, notes de déploiement

Ajoutez des notes d’architecture simples en langage courant : qui parle à qui, et pourquoi. Un petit diagramme est optionnel, mais quelques phrases suffisent généralement. Exemple : « Le frontend React appelle l’API Go. L’API lit et écrit dans PostgreSQL. Les jobs en arrière-plan tournent comme un worker séparé. »

Enfin, incluez un changelog ou des notes de release versionnées pour la build de la remise. Cela peut être un CHANGELOG.md ou un fichier « release notes » court qui indique le commit/tag exact, ce qui a été livré et les problèmes connus.

Si le code a été exporté depuis une plateforme comme Koder.ai, notez le type de projet généré (web, serveur, mobile), la chaîne d’outils attendue (par exemple React, Go, PostgreSQL, Flutter) et les versions OS/outils recommandées pour reproduire la build.

Variables d’environnement : inventaire et documentation

Les variables d’environnement sont souvent la raison pour laquelle une « appli fonctionnelle » échoue juste après le transfert. Une bonne checklist traite ces variables comme faisant partie du produit, pas comme un détail.

Commencez par rédiger un inventaire qu’une nouvelle équipe peut suivre sans deviner. Gardez-le en langage clair et incluez un format d’exemple (sans secrets réels). Si une variable est optionnelle, indiquez ce qui se passe si elle est absente et quelle valeur par défaut est utilisée.

Une façon simple de présenter l’inventaire :

• Nom de la variable, ce qu’elle contrôle, et un exemple de format
• Requise vs optionnelle, plus le comportement par défaut
• Où elle est définie (CI, tableau de bord d’hébergement, fichier local .env)
• Quels environnements nécessitent des valeurs différentes (dev, staging, production)
• Qui est propriétaire des changements (client, agence, ou partagé)

Signalez clairement les différences par environnement. Par exemple, la staging peut pointer vers une base de test et un fournisseur de paiement sandbox, tandis que la production utilise des services live. Notez aussi les valeurs qui doivent correspondre entre systèmes, comme les URL de callback, les origines autorisées ou les identifiants de bundle mobile.

Documentez où chaque valeur vit aujourd’hui. Beaucoup d’équipes répartissent les valeurs : fichiers .env locaux pour le dev, variables CI pour les builds et paramètres d’hébergement pour l’exécution. Si vous avez utilisé Koder.ai pour exporter l’app, incluez un fichier .env.example et une note courte sur les variables à remplir avant la première build.

Enfin, prouvez qu’il n’y a pas de secrets cachés dans le repo. Ne vous contentez pas de vérifier les fichiers actuels. Passez en revue l’historique des commits pour des clés accidentelles, d’anciens fichiers .env ou des identifiants copiés dans des configs d’exemple.

Exemple concret : un frontend React et une API Go peuvent nécessiter API_BASE_URL pour le web, et DATABASE_URL plus JWT_SIGNING_KEY pour le backend. Si la staging utilise un domaine différent, écrivez les deux valeurs et indiquez où les modifier, pour que la nouvelle équipe n’envoie pas par erreur les paramètres de staging en production.

Rotation des secrets : transférer en sécurité, puis prouver que ça marche

Un transfert n’est complet que lorsque le client contrôle chaque identifiant dont l’app a besoin. Cela signifie faire une rotation des secrets, pas seulement les partager. Si une agence (ou un ancien contractant) possède encore des clés actives, vous laissez une porte ouverte que vous ne pouvez pas auditer.

Commencez par établir un inventaire complet. Ne vous arrêtez pas aux mots de passe de base de données. Incluez les clés API tierces, secrets clients OAuth, secrets de signature de webhooks, clés de signature JWT, identifiants SMTP, clés d’accès au stockage et tout token « temporaire » présent dans le CI.

Voici une checklist simple pour le jour de la rotation :

• Lister chaque secret, ce qu’il déverrouille et où il est actuellement défini (fichiers env locaux, CI, tableau de bord d’hébergement, vault)
• Créer de nouvelles identifiants sous les comptes du client, et définir un propriétaire pour chacun (personne et boîte d’équipe)
• Mettre à jour la config de l’app pour utiliser les nouvelles valeurs, puis déployer d’abord en staging/test
• Révoquer les anciens identifiants dès que les nouveaux sont confirmés fonctionnels
• Documenter précisément les étapes de rotation pour que la prochaine rotation soit banale et rapide

Après la rotation, prouvez que rien n’a cassé. Faites des tests « utilisateur réel » plutôt que de vérifier seulement les logs.

Concentrez-vous sur les flux qui dépendent des secrets :

• Connexion, inscription, réinitialisation de mot de passe et rafraîchissement de token
• Paiements, envoi d’e-mails et uploads de fichiers
• Webhooks (vérification de signature et gestion des retries)
• Jobs en arrière-plan ou tâches planifiées qui appellent des API externes
• Actions admin touchant des endpoints privilégiés

Exemple : si vous avez exporté un projet depuis Koder.ai et que l’app utilise un fournisseur de paiement et d’envoi d’e-mails, faites la rotation des deux clés, redéployez, puis effectuez une petite transaction de test et envoyez un e-mail de test. Ce n’est qu’après succès qu’il faut révoquer les clés détenues par l’agence.

Enfin, documentez où les secrets seront stockés à l’avenir (vault, variables CI ou paramètres d’hébergement), qui peut les modifier et comment revenir en arrière en cas d’erreur lors d’une rotation.

Migrations de base de données et gestion des données

Un transfert peut sembler « terminé » alors que la base de données est la première à casser. Traitez les migrations et les données comme un produit à part entière : versionnées, reproductibles et testées.

Commencez par noter la version actuelle de la base de données et où se trouvent les migrations dans le dépôt. Soyez précis : le chemin du dossier, le pattern de nommage et l’ID de migration le plus récent (ou timestamp). Si vous utilisez PostgreSQL (fréquent avec des backends Go), notez aussi les extensions requises.

Que documenter (pour que quelqu’un d’autre puisse les exécuter)

Incluez un court runbook répondant à ces questions :

• Quelle commande lance les migrations, et dans quel ordre exécuter les étapes (créer la base, appliquer les migrations, puis les seeds)
• En quoi cela diffère selon l’environnement (local, staging, production), y compris les flags « mode sûr »
• Si les migrations sont automatiques au déploiement ou doivent être lancées manuellement, et qui est autorisé à les exécuter
• Stratégie de seed : aucune, uniquement démo, ou enregistrements minimaux requis (utilisateur admin, réglages par défaut)
• Plan de rollback : ce qui peut être inversé et ce qui ne peut pas l’être (par exemple les suppressions destructrices de colonnes)

Les rollbacks méritent de l’honnêteté. Certains changements ne se réparent qu’avec une restauration depuis une sauvegarde. Indiquez-le clairement en langage clair et associez-le à une étape de backup (snapshot avant déploiement, vérification du processus de restauration).

Avant de conclure le transfert, exécutez les migrations sur une copie des données de production si possible. Cela permet de détecter les requêtes lentes, index manquants et problèmes qui ne se manifestent qu’avec des données réelles. Un test réaliste consiste à exporter le code, définir les variables d’environnement, restaurer un dump anonymisé, puis appliquer les migrations depuis zéro. Cet exercice valide une grande partie de la checklist.

Si l’app a été construite sur une plateforme comme Koder.ai puis exportée, vérifiez que les fichiers de migration et les scripts de seed sont inclus dans l’export et correctement référencés par le processus de démarrage du backend.

Build et CI : rendre ça reproductible

Un transfert n’est complet que si quelqu’un d’autre peut reconstruire l’app depuis zéro sur une machine propre. Votre checklist doit inclure les commandes de build exactes, les versions requises et le résultat attendu (par exemple : « bundle web dans /dist », « binaire API nommé », « emplacement APK Flutter »).

Indiquez les outils et gestionnaires de paquets que vous utilisez réellement, pas ce que vous pensez utiliser. Pour une stack typique cela peut être Node.js (npm ou pnpm) pour un frontend React, la toolchain Go pour le serveur, les outils client PostgreSQL pour la configuration locale, et le SDK Flutter pour le mobile.

Rendez l’installation des dépendances prévisible. Confirmez que les lockfiles sont commités (package-lock.json, pnpm-lock.yaml, go.sum, pubspec.lock) et faites une installation fraîche sur un nouvel ordinateur ou un conteneur propre pour prouver que ça marche.

Documentez ce que fait le CI, étape par étape, afin qu’il puisse être copié vers un autre fournisseur CI si nécessaire :

• Installer les dépendances (avec lockfiles)
• Exécuter tests et lint
• Produire les builds (bundle web, binaire serveur, build mobile)
• Produire des artefacts (zip, image Docker, bundle de release)
• Conserver les logs et métadonnées de build (version, commit, date)

Séparez la config au moment du build de la config au runtime. La config de build modifie ce qui est compilé (par exemple une API baked dans un bundle web). La config runtime est injectée au démarrage (URL DB, clés API et feature flags). Les mélanger est une raison fréquente pour que « ça marche en CI » mais que ça échoue en production.

Fournissez une recette simple de vérification locale. Même une courte série de commandes suffit :

# Web
pnpm install
pnpm test
pnpm build

# API
go test ./...
go build ./cmd/server

# Mobile
flutter pub get
flutter test
flutter build apk

Si vous exportez depuis une plateforme comme Koder.ai, incluez tous les fichiers CI générés ou presets de build utilisés pendant le déploiement afin que le client puisse reproduire la même build hors plateforme.

Scripts de déploiement et processus de release

Une bonne checklist ne s’arrête pas à « voici le dépôt ». Elle explique aussi comment le code devient un service en fonctionnement et qui appuie sur le bouton.

Commencez par décrire comment les déploiements se font aujourd’hui : entièrement manuels (quelqu’un exécute des commandes sur un serveur), pilotés par CI (un pipeline build et déploie) ou via une plateforme hébergée. Indiquez où vivent les configs et quels environnements existent (dev, staging, production).

Rendez les étapes de release reproductibles. Si le processus dépend d’une personne qui se rappelle 12 commandes, transformez-les en scripts et notez les permissions requises.

Ce qu’il faut inclure avec le package de déploiement

Donnez au client ce dont il a besoin pour déployer le jour J :

• Commandes de build et d’exécution (et versions exactes de Node, Go, Flutter, etc.)
• Scripts de déploiement (shell, cibles Makefile ou configs de pipeline)
• Accès requis : rôles de compte cloud, registre de conteneurs, DNS, admin DB
• Notes de configuration d’environnement : où sont définies les vars et comment elles diffèrent par env
• Convention de nommage des releases : tags/releases et comment identifier ce qui est en cours d’exécution

Mettez-vous d’accord sur les attentes en matière d’indisponibilité. Si « zéro downtime » est requis, expliquez ce que cela signifie en pratique (blue-green, rolling deploy, fenêtre lecture seule pour les migrations). Si une indisponibilité est acceptable, définissez une fenêtre claire.

Les assets statiques et les caches sont des points de défaillance fréquents. Notez comment les assets sont construits et servis, quand purger les caches et si un CDN est impliqué.

Rollback exécutable

Un rollback doit être une recette courte et testée liée à un tag ou un ID de release. Par exemple : déployer le tag précédent, restaurer le snapshot DB antérieur si nécessaire, et invalider les caches.

Si l’app a été créée sur Koder.ai puis exportée, mentionnez le dernier snapshot connu comme bon et la version d’export exacte pour que le client puisse associer rapidement le code à une release fonctionnelle.

Étapes détaillées : vérifier la build après export

La vérification est le moment où l’on sait si le transfert est réel. L’objectif est simple : une nouvelle personne peut prendre le code exporté, l’installer et obtenir la même appli sans supposition.

Avant de commencer, notez ce à quoi ressemble l’instance « correcte » : la version de l’app en cours, le commit/tag actuel (si présent), et un ou deux écrans ou réponses d’API clés à comparer. Si l’export vient d’une plateforme comme Koder.ai, notez le snapshot ou l’horodatage d’export pour prouver que vous testez l’état le plus récent.

1. Confirmer que l’export correspond à la production : vérifiez l’historique des commits, les release notes ou les métadonnées de build. Comparez une version visible ou un petit comportement (par ex. un libellé UI spécifique) avec l’app en cours d’exécution.
2. Configurer variables d’environnement et secrets : créez la config cible (local et staging). Utilisez l’inventaire fourni et assurez-vous qu’aucune valeur n’est codée en dur dans le dépôt.
3. Installer les dépendances et exécuter les tests : faites une installation propre (sans caches node_modules/vendor). Lancez les tests unitaires et lint tels que documentés.
4. Exécuter les migrations et démarrer en local : démarrez la base, appliquez les migrations dans l’ordre et lancez l’app. Vérifiez que l’app peut lire/écrire des données de base et qu’il n’y a pas de migrations en attente.
5. Déployer en staging, smoke test, puis promouvoir : déployez en utilisant les scripts/pipeline que vous comptez utiliser en production. Ne promouvez que si la staging correspond aux attentes.

Pour les tests de fumée, restez concis et axés sur le risque :

• Connexion/déconnexion (ou création d’un utilisateur test)
• Un flux principal de bout en bout (créer-modifier-enregistrer)
• Un e-mail/webhook/transaction de paiement si applicable
• Gestion d’erreur basique (mauvaise saisie, enregistrement manquant)
• Les logs n’affichent pas de crashs répétés ou d’erreurs liées aux secrets

Si quelque chose échoue, capturez la commande exacte, la sortie d’erreur et les vars d’environnement utilisées. Ces détails économisent des heures lors d’un changement de propriétaire.

Erreurs courantes de transfert et comment les éviter

Le moyen le plus rapide de transformer un transfert en intervention d’urgence est de supposer que « le code suffit ». Une bonne checklist se concentre sur les petits détails ennuyeux qui déterminent si le client peut réellement exécuter et modifier l’app sans vous.

Les erreurs qui causent le plus de problèmes

La plupart des problèmes suivent quelques schémas :

• Les secrets ne sont pas rotatés, donc des mots de passe, clés API ou tokens cloud d’agence fonctionnent encore après la remise.
• Les variables d’environnement sont incomplètes parce que certaines valeurs vivent uniquement dans le CI ou le tableau d’hébergement, et pas dans le dépôt.
• Des modifications ponctuelles en production sont oubliées, comme un hotfix, une édition manuelle de la DB ou un toggle de config directement sur le serveur.
• Les migrations fonctionnent localement mais échouent en production à cause de permissions manquantes, extensions ou ownership du schéma.
• Il n’y a pas de plan de rollback, ni de release taggée (ou notes de release) pour revenir en arrière après un déploiement raté.

Comment les prévenir (sans ajouter des semaines)

Planifiez la rotation et le nettoyage des accès comme une tâche programmée, pas comme un « quand on aura le temps ». Fixez une date où les comptes d’agence sont retirés, les clés régénérées et le client confirme qu’il peut déployer uniquement avec ses identifiants.

Pour les vars d’environnement, faites un inventaire simple depuis trois endroits : le dépôt, le système CI et l’interface d’hébergement. Validez ensuite en lançant une build propre depuis une machine ou un conteneur vierge.

Pour les migrations, testez avec le même rôle DB que celui que le déploiement de production utilisera. Si la production nécessite des étapes élevées (activation d’extension), documentez-les et clarifiez la propriété.

Exemple réaliste : après export depuis Koder.ai, le client déploie avec succès mais les jobs en arrière-plan échouent parce qu’une URL de queue était définie uniquement dans le tableau d’hébergement. Un simple audit des vars d’environnement l’aurait détecté. Ajoutez un tag de release et un rollback documenté (par ex. « redéployer le tag v1.8.2 et restaurer le dernier snapshot ») et l’équipe évite l’indisponibilité.

Checklist finale, un exemple simple et prochaines étapes

Si vous ne gardez qu’une page de cette checklist, gardez celle-ci. L’objectif est simple : un clone propre doit s’exécuter sur une machine neuve, avec de nouveaux secrets, et une base de données qui peut évoluer en toute sécurité.

Vérifications rapides (à faire depuis un clone propre)

Exécutez ces vérifications sur un laptop qui n’a jamais vu le projet (ou dans un conteneur/VM propre). C’est le moyen le plus rapide de détecter des fichiers manquants, des hypothèses cachées et d’anciens identifiants.

• Build depuis zéro : installer les dépendances, lancer les tests (si présents) et produire une build de release sans modification manuelle.
• La config fonctionne : définir les variables d’environnement documentées et confirmer que l’app démarre avec une config propre ou un fichier env.
• Les secrets sont rotatés : vérifiez que l’app fonctionne avec les nouvelles clés, puis révoquez les anciennes et confirmez qu’il n’y a pas de régression.
• Les migrations s’exécutent proprement : partir d’une DB vide, appliquer les migrations, démarrer l’app et tester un flux basique.
• Le chemin de déploiement est réel : exécuter le script de déploiement ou le workflow CI une fois et confirmer qu’il produit le même résultat.

Exemple de transfert simple

Une agence remet un frontend React, une API Go et une base PostgreSQL. L’équipe cliente clone le repo, copie le .env.example fourni en variables réelles, crée de nouveaux identifiants pour la DB, le fournisseur d’e-mails et les APIs tierces. Ils lancent go test (ou la commande de test convenue), buildent le frontend React, appliquent les migrations sur une instance Postgres fraîche et démarrent les deux services. Enfin, ils déploient en utilisant le script documenté et confirment que le même commit peut être reconstruit plus tard.

Prochaines étapes

Gardez le transfert court et piloté. Une présentation de 30 à 60 minutes vaut souvent mieux qu’un long document.

• Planifiez une walkthrough et enregistrez les décisions (qui gère les déploiements, les secrets et la DB).
• Désignez un propriétaire pour l’accès production et un backup.
• Mettez d’accord un commit hash d’« acceptance build » et taggez-le.
• Si vous avez utilisé Koder.ai, exportez le code source, puis utilisez snapshots et rollback lors du premier déploiement client pour réduire les risques.