Erreurs de click deploy : pourquoi les déploiements Salesforce échouent et comment les corriger

En bref : un click deploy échoue rarement à cause du bouton. Il échoue parce que la Metadata API de Salesforce rejette le paquet, et presque chaque rejet entre dans cinq catégories : une dépendance manquante, une couverture de tests insuffisante, une version d'API inconnue de la cible, une limite de taille de la plateforme, ou une modification que l'API ne sait pas faire. Lisez la première erreur, corrigez la cause dans la source et relancez une validation avant de déployer.

Que se passe-t-il quand vous cliquez sur déployer dans Salesforce ?

Quel que soit l'outil, le mécanisme sous-jacent est le même. L'outil construit un manifeste package.xml et un .zip des métadonnées sélectionnées, les envoie à la Metadata API, puis Salesforce compile, exécute les tests Apex au niveau choisi et enregistre le résultat. Si les outils point-and-click sont nouveaux pour vous, commencez par le fonctionnement et le coût de ClickDeploy.

Deux règles de la plateforme expliquent la plupart des surprises :

• Par défaut, c'est tout ou rien. Une seule erreur annule tout le déploiement. La référence de la Salesforce CLI propose une option pour ignorer les erreurs et sauter le rollback, et précise de ne jamais l'utiliser pour un déploiement en production.
• Sandbox et production ne testent pas pareil. Le niveau par défaut n'exécute aucun test en sandbox, alors que les déploiements en production contenant des classes ou triggers Apex exécutent tous les tests locaux. C'est pourquoi un déploiement peut réussir en UAT et échouer en production.

Pourquoi les click deploys échouent-ils ?

1. Une dépendance manque

Le paquet fait référence à un élément absent de l'org cible : un champ sans son objet, un Flow sans les champs qu'il lit, un objet enfant sans son parent. Copado Essentials, l'outil anciennement appelé ClickDeploy, documente un cas classique : déployer seul un objet de détail renvoie Cannot set sharingModel to ControlledByParent on a CustomObject without a MasterDetail relationship field. Le correctif consiste à ajouter l'objet parent au déploiement, même s'il n'a pas changé.

2. La couverture des tests Apex est trop faible

Salesforce exige qu'au moins 75 % de votre code Apex soit couvert par des tests unitaires pour déployer en production, et chaque trigger doit avoir au moins une ligne couverte. Avec RunSpecifiedTests, la règle change : les tests indiqués doivent couvrir à 75 % chaque classe et chaque trigger du paquet, pris individuellement. La solution, ce sont de meilleurs tests, pas un autre niveau de test.

3. La version d'API est plus récente que la cible

Une erreur comme Invalid api version apparaît généralement autour d'une fenêtre de release, quand votre sandbox tourne déjà sur la prochaine version de Salesforce et pas encore la production. Winter '27 en est un exemple actuel : les sandboxes sont passées en preview fin août 2026, tandis que les instances de production sont mises à niveau sur plusieurs week-ends jusqu'en octobre ; vérifiez donc votre instance sur Salesforce Trust. La recommandation de Copado est de ramener la version d'API du composant à une version prise en charge par la production, puis de redéployer.

4. Le paquet est trop volumineux

La propre bibliothèque de déploiement de Salesforce, source-deploy-retrieve, avertit lorsqu'un déploiement approche des limites de la Metadata API : 10 000 fichiers et environ 39 Mo compressés. Les sélections par wildcard et les déploiements d'objets complets les atteignent en premier. Découpez la release, ou ne livrez que ce qui a changé grâce aux déploiements delta.

5. L'API refuse la modification

• Flows actifs. Le guide des Flows de Copado indique qu'on ne peut pas déployer une version de Flow active dans l'org cible. Clonez-la en une nouvelle version dans la source, déployez-la puis activez-la dans la cible. Il prévient aussi que déployer le composant FlowDefinition renvoie souvent invalid version number.
• Conversions de picklist. Une picklist classique ne peut pas être convertie en global value set par déploiement. Le contournement de Copado consiste à créer un nouveau champ basé sur le global value set et à retirer l'ancien.

Comment diagnostiquer un click deploy en échec, étape par étape ?

1. Lisez la première erreur, pas la dernière. Un seul champ manquant peut déclencher des dizaines d'erreurs en cascade.
2. Identifiez la catégorie. Dépendance, couverture, version, taille ou modification non prise en charge. Chacune a son propre correctif.
3. Corrigez la source, pas la cible. Modifier la production à la main fausse la comparaison suivante.
4. Validez à nouveau. Lancez un déploiement check-only avec le même niveau de test que la production.
5. Déployez le paquet validé. Notre checklist du click deploy détaille les niveaux de test et le quick deploy.

Qu'est-ce qu'un click deploy réussi ne vous dit pas ?

Un déploiement au vert signifie seulement que Salesforce a accepté le paquet. Il ne garantit pas que la cible correspond à la source :

• Permissions de profil désactivées. Copado documente que la Metadata API omet les user permissions désactivées dans les profils récupérés : une permission désactivée dans la source peut donc rester active dans la cible.
• Suppressions. Elles voyagent à part, sous forme de destructive changes avant ou après le déploiement.
• Le travail d'un collègue. Les déploiements d'org à org ne gardent aucun historique partagé, donc un second déploiement peut écraser le premier sans bruit. Déployer depuis une branche Git règle ce problème.

Qui est Tekunda, et comment Serpent réduit-il les déploiements en échec ?

Tekunda est la société de conseil et de produits Salesforce derrière Serpent, la plateforme DevOps qu'elle utilise pour ses propres livraisons clients. Serpent conserve l'expérience de sélection au clic, mais chaque changement passe par Git, une pull request et une validation avec tests Apex avant d'atteindre l'org suivante, avec une revue de code IA sur tous les forfaits, y compris le gratuit. Rien n'est installé dans votre org. Les équipes sur Copado Essentials, Gearset, Salto, AutoRABIT, Flosum ou Blue Canvas peuvent suivre notre parcours de migration, et d'autres guides pratiques se trouvent dans la bibliothèque SF Guides.

FAQ

Pourquoi mon déploiement réussit-il en sandbox mais échoue-t-il en production ?

Les sandboxes n'exécutent aucun test Apex par défaut, alors que la production exécute les tests locaux et impose 75 % de couverture. Validez d'abord contre la production avec le même niveau de test.

Que signifie « invalid api version » ?

Votre composant utilise une version d'API que l'org cible ne prend pas encore en charge, souvent pendant une fenêtre de release. Abaissez la version du composant et redéployez.

Puis-je ignorer les erreurs et déployer quand même ?

La Salesforce CLI dispose d'une option qui ignore les erreurs et saute le rollback, mais sa propre référence déconseille formellement de l'utiliser en production.

Combien de composants un déploiement peut-il contenir ?

La Metadata API limite un déploiement à 10 000 fichiers et environ 39 Mo compressés. Découpez les releases plus importantes.