CI/CD 2GP : automatiser les builds de packages unlocked et manages

Reponse courte : un pipeline CI/CD 2GP cree une version de package a chaque merge, installe cette version dans une scratch org neuve, execute les tests contre elle et ne promeut que ce qui passe. Le pipeline lui-meme tient en cinq commandes. Ce qui casse vraiment les builds 2GP des mois plus tard, ce n'est pas le pipeline, ce sont les decisions d'ancestry et de namespace prises la premiere semaine.

Que fait concretement un pipeline CI/CD 2GP ?

Cinq etapes, dans cet ordre :

1. Valider la source. Analyse statique et linting sur la pull request, avant toute construction.
2. Construire une version de package. Une version beta, produite depuis la source et non depuis une org.
3. Installer dans un environnement propre. Une scratch org neuve prouve que le package s'installe, ce qui n'est pas la meme affirmation que "le code se deploie".
4. Tester contre le package installe. Le code sous namespace se comporte differemment une fois package, donc les tests s'executent apres l'installation.
5. Promouvoir ce qui passe. La promotion est la porte, et c'est la seule etape qui doit etre difficile a declencher.

La distinction qui compte : deployer des metadonnees prouve que cela compile dans une org que vous controlez. Installer une version de package prouve que cela fonctionne dans une org que vous ne controlez pas.

Qu'est-ce qui change entre unlocked et managed 2GP ?

• Les packages unlocked servent a votre propre parc d'orgs ou a celui d'un client. Pas de namespace obligatoire, pas d'ancestry, pas de security review. Les versions sont bon marche et jetables.
• Le managed 2GP sert a la distribution : namespace enregistre, protection de la propriete intellectuelle, ancestry, chemins de mise a niveau pour les abonnes et security review AppExchange.

La forme du pipeline est identique. Les consequences d'une mauvaise promotion, non : une version unlocked regrettee se remplace, une version manage promue devient une API publique pour toujours.

Comment construire le pipeline, etape par etape ?

1. Authentifier le Dev Hub sans interaction. Un flux JWT bearer avec un certificat stocke dans le coffre de votre CI. Le Dev Hub doit etre l'org proprietaire du namespace, sinon la creation de version echoue immediatement.
2. Creer la version : sf package version create --package MyPackage --code-coverage --installation-key-bypass --wait 60. Recuperez l'identifiant 04t comme sortie de pipeline.
3. Lancer une scratch org : sf org create scratch --definition-file config/project-scratch-def.json --duration-days 1 --wait 10.
4. Installer et tester : sf package install --package 04tXXXX --wait 20, puis sf apex run test --test-level RunLocalTests --code-coverage --wait 30.
5. Promouvoir, uniquement sur la branche de release : sf package version promote --package [email protected].

Tout ce qui precede l'etape 5 tourne sur chaque pull request. L'etape 5 tourne sur une seule branche, derriere une validation humaine.

Comment reussir ancestry et namespace pour que les builds ne cassent pas plus tard ?

Ancestry

L'ancestry ne concerne que le managed 2GP, et c'est la que les pipelines automatises derapent en silence. Salesforce exige que l'ancetre indique soit le numero de version promue le plus eleve du package, et seules les versions promues a l'etat managed-released peuvent servir d'ancetre (Salesforce Developers). Trois regles a coder dans votre pipeline :

• Utilisez le mot-cle. "ancestorVersion": "HIGHEST" dans sfdx-project.json fixe automatiquement l'ancetre a la version promue la plus elevee, exactement ce dont la CI a besoin. Les alternatives sont un major.minor.patch explicite ou un ancestorId.
• Ne promouvez jamais un build a moitie vert. Une version promue devient l'ancetre suivant. Promouvez du bruit et votre lignee en herite.
• Sachez ce que coute la rupture de la lignee. Vous pouvez briser le versionnage lineaire avec --skip-ancestor-check, mais les packages ne se mettent a jour que le long de la lignee : tout abonne reste sur une version abandonnee perd son chemin de mise a niveau.

Les versions patch ont leur propre regle : un patch ne peut pas etre l'ancetre direct d'une version non patch.

Namespace

• Liez le namespace au Dev Hub auquel votre CI s'authentifie. Ce seul decalage est l'echec le plus frequent au premier passage.
• Le 2GP autorise plusieurs packages dans un meme namespace. Separez par repertoire de package dans sfdx-project.json et declarez explicitement les dependances entre packages, avec leurs versions.
• Vous venez du 1GP ? Salesforce a rendu Package Migrations generalement disponible en Summer '25 : conversion d'un package 1GP en 2GP avec sf package convert et migration des abonnes installes.

Comment garder un pipeline 2GP rapide ?

• Mutualisez vos scratch orgs. La creation d'org, et non celle du package, est generalement l'etape la plus lente. Des orgs prechauffees la sortent du chemin critique.
• Calibrez les tests par etape. Tests pertinents sur la pull request, RunLocalTests avant la promotion.
• Mettez la version en cache. Si la source n'a pas change, ne reconstruisez pas le package.

Vous pouvez assembler tout cela avec la CLI Salesforce plus GitHub Actions, Azure Pipelines ou CumulusCI. Serpent vous donne le meme pipeline sans le YAML : workflows natifs 1GP, 2GP et managed package, resolution des dependances entre packages et gestion des versions chez les abonnes sur tous les plans, avec pooling de scratch orgs prechauffees sur Scale. D'autres guides de build et de release sont dans SF Guides.

FAQ

Peut-on automatiser entierement la creation de packages 2GP ?

Oui. Creation de version, installation, tests et promotion sont tous des commandes CLI, donc le cycle complet tourne sans intervention. Gardez malgre tout la promotion derriere une validation humaine.

Qu'est-ce que l'ancestry en 2GP ?

La filiation declaree entre versions de package manage. Elle definit le chemin de mise a niveau des abonnes, car les packages ne se mettent a jour que le long de cette lignee.

Les packages unlocked ont-ils besoin d'un namespace ?

Non. Ils peuvent s'en passer, d'ou leur interet pour un parc d'orgs interne. Le managed 2GP exige un namespace enregistre et lie a votre Dev Hub.

Pourquoi ma creation de version echoue-t-elle sur l'ancestry ?

Le plus souvent parce que l'ancetre indique n'est pas une version promue en managed-released, ou parce qu'une version patch a ete definie comme ancetre d'une version non patch.

La CI doit-elle promouvoir chaque build vert ?

Non. La promotion est irreversible en pratique et fixe l'ancetre suivant : elle appartient a une branche de release derriere une validation, pas a chaque merge.