Lab 3.1 - Configurer la pipeline CI/CD jusqu'à la production¶

Niveau : 3 Release Manager

Durée : ~75 min

Vous allez : transformer une pipeline à deux étages en une pipeline à quatre étages qui atteint la production, donner à chaque étage son org et un identifiant avec lequel un vrai projet peut vivre, et publier tout cela de la façon dont toute modification atteint une branche majeure : par une Pull Request.

La situation¶

Ouvrez le panneau DevOps Pipeline et regardez ce que Victor a laissé.

integration (1) et uat, chacune avec son org (2), et les branches de feature que vos collègues ont en cours. Le travail atteint les testeurs métier, et là il s'arrête. Il n'y a pas de preprod, et main, la production, est une branche où rien ne déploie : toutes les livraisons jusqu'ici ont atteint la production à la main, ce qui est exactement le genre de livraison dont personne ne peut rien dire après coup.

Et les deux étages qui existent atteignent leurs orgs par un raccourci. La CI se connecte à helios-integration et helios-uat avec SFDX_AUTH_URL_INTEGRATION et SFDX_AUTH_URL_UAT, deux secrets contenant des refresh tokens OAuth de longue durée. Le Niveau 1 vous a dit que c'était une exception pour des scratch orgs jetables. Trois choses ne vont pas avec eux sur un vrai projet, et quelqu'un vous demandera pourquoi vous y passez une heure :

1. Ils ne peuvent pas être renouvelés. En changer un veut dire se réauthentifier, en tant qu'humain, dans un navigateur
2. Ce sont des identifiants au porteur sans portée. Quiconque lit le secret dispose de tout ce dont cet utilisateur dispose, depuis n'importe où, jusqu'à révocation
3. Ils sont liés à une personne. Quand cette personne part ou que son token est réinitialisé, le pipeline s'arrête, et personne ne sait pourquoi

L'alternative est un flow JWT via une External Client App : un certificat que vous détenez, un utilisateur pré-autorisé, aucun mot de passe nulle part, et une révocation en supprimant une application. sfdx-hardis le met en place pour vous, org par org, et écrit la configuration de branche au passage.

C'est votre première semaine. Rien de tout cela n'est inhabituel : la plupart des projets démarrent avec les étages dont ils ont besoin le premier jour, et finir la pipeline attend le jour où quelqu'un a besoin de livrer correctement.

Avant de commencer¶

• Niveaux 1 et 2 terminés
• helios-prod toujours connectée dans Orgs Manager. C'est l'org Developer Edition à laquelle vous vous êtes inscrit au Niveau 1, et le Dev Hub de vos scratch orgs. À partir de ce lab, c'est aussi la production
• Une org Developer Edition gratuite de plus, créée sur developer.salesforce.com/signup exactement comme la première, et connectée dans Orgs Manager avec l'alias helios-preprod
• Les deux alimentées : Welcome page > Training: Level 3 > Set up one of my training orgs, une fois pour helios-preprod et une fois pour helios-prod
• helios-integration et helios-uat connectées dans Orgs Manager, comme depuis le Niveau 1
• Sur integration dans VS Code, avec rien en attente dans le panneau Source Control

Les étapes¶

1. Décider la forme¶

Quatre questions, et leurs réponses sont toute la pipeline :

Si vous ne savez pas les énoncer en une phrase chacune, les configurer n'y changera rien.

preprod gagne sa place de deux façons. C'est la dernière répétition avant la production, une org qui contient ce que la production contient et dans laquelle personne ne travaille : une livraison qui s'y déploie proprement n'a presque plus de surprises devant elle. Et c'est de là que partent les hotfixes, ce dont parle le Lab 3.7.

L'ordre de ce lab découle d'une règle : une branche doit exister avant qu'une org puisse lui être attachée. Les branches viennent donc d'abord, puis leur protection, puis leurs orgs.

2. Créer la branche preprod¶

main existe déjà : c'est la branche par défaut de tout fork. preprod non, et elle part de main, parce qu'elle contient ce que la production contient.

Dans votre fork (votre copie personnelle du repository du cours sur GitHub, par exemple github.com/my-username/sfdx-hardis-training), ouvrez la page Branches : le compteur de branches à côté du sélecteur de branche, ou github.com/my-username/sfdx-hardis-training/branches. Cliquez sur New branch en haut à droite. Tapez preprod comme nom (1), laissez la source sur votre fork et main (2), et cliquez sur Create new branch (3).

Prévenez ensuite VS Code : dans le panneau Source Control, menu ..., Pull, Push > Fetch. Les étapes suivantes listent les branches de votre fork, et une branche que VS Code n'a pas récupérée n'est pas dans la liste.

3. Protéger preprod et main¶

À partir de maintenant, personne ne pousse sur une branche majeure : ni un contributeur, ni vous. Toute modification atteint integration, uat, preprod et main par une Pull Request dont les contrôles sont verts, et GitHub l'impose au lieu de faire confiance à chacun pour s'en souvenir. Depuis le Lab 1.2, integration et uat fonctionnent ainsi : la mise en place de l'environnement les a protégées. preprod et main sont à vous de protéger, et un release manager le fait le jour où les branches rejoignent la pipeline, pas après le premier mauvais merge.

Dans votre fork (github.com/my-username/sfdx-hardis-training), cliquez sur Settings (1), puis Branches (2) dans le menu de gauche. Les deux règles (4) sont celles que la mise en place de votre environnement a créées au Lab 1.2. Cliquez sur Add rule (3).

Le formulaire est long, et cinq choses y comptent. L'image est la règle d'integration, ouverte depuis la liste ci-dessus : elle montre donc les valeurs que vous êtes sur le point de poser.

1. Branch name pattern (1) : preprod
2. Cochez Require a pull request before merging (2), et décochez Require approvals en dessous : vous travaillez seul ici, et GitHub ne vous laisse jamais approuver votre propre Pull Request. Sur un vrai projet, demandez une approbation
3. Cochez Require status checks to pass before merging (3). Une zone de recherche apparaît en dessous. Tapez Simulate et choisissez Simulate Deployment to Major Org, puis tapez Mega et choisissez Mega-Linter. Les deux atterrissent dans Status checks that are required : ce sont les deux contrôles que lance chaque Pull Request de ce cours
4. Cochez Do not allow bypassing the above settings (4). Sans cela, le propriétaire du repository, c'est-à-dire vous, a encore une case pour pousser ou merger quand même
5. Cliquez sur Create en bas. Sur une règle existante, le même bouton affiche Save changes (5)

Puis Add rule à nouveau, pour main, avec les mêmes réglages. De retour sur la liste : quatre règles, integration, uat, preprod et main.

La zone de recherche ne propose que les contrôles qui ont tourné sur ce repository dans les sept derniers jours. Les deux ont tourné sur vos Pull Requests du Niveau 2, ils y sont donc, sauf si vous avez fait une longue pause : dans ce cas ouvrez d'abord n'importe quelle Pull Request vers integration, et ses contrôles les remettent dans la liste.

gh api -X PUT repos/<your-handle>/sfdx-hardis-training/branches/preprod/protection \
  -F "required_pull_request_reviews[required_approving_review_count]=0" \
  -f "required_status_checks[contexts][]=Simulate Deployment to Major Org" \
  -f "required_status_checks[contexts][]=Mega-Linter" \
  -F "required_status_checks[strict]=false" -F enforce_admins=true -F restrictions=null

4. Configurer integration et son org : Add/Configure Org¶

Passons aux orgs. Une seule commande fait tout pour une branche : elle écrit la configuration de branche, l'org dans laquelle elle déploie et la branche dans laquelle elle merge, crée l'identifiant avec lequel la CI se connecte, et déploie l'External Client App dans l'org. Vous la lancez une fois par branche majeure, en commençant par integration.

Dans le panneau DevOps Pipeline, cliquez sur l'engrenage (1) en haut à droite et choisissez Add/Configure Org (2).

La commande tourne dans un panneau et pose une question à la fois (1), avec les réponses à cliquer en dessous (2). La voici à la deuxième question, avec helios-integration déjà choisie.

Elle pose une douzaine de questions, dans cet ordre :

1. Please select or login into the org you want to configure the SF CLI Authentication - helios-integration. La commande en fait votre org par défaut et, parce que cela a changé, VS Code relance la même commande. Choisissez helios-integration une deuxième fois dans le nouveau panneau et continuez à partir de là
2. What is the name of the git branch you want to configure Automated CI/CD deployments from? - integration. La liste est construite depuis les branches de votre fork, et les branches dont le nom contient un / sont écartées, c'est pourquoi aucune branche de feature n'est proposée
3. What is the base URL or domain or the org you want to connect to, as integration related org ? Prenez 🧪 Sandbox or Scratch org (test.salesforce.com) : helios-integration est une scratch org, et une scratch org se connecte comme une sandbox. La réponse surlignée est celle du dessus, 📝 Custom login URL : lisez donc cette liste plutôt que d'appuyer sur Entrée
4. What are the target git branches that integration will be able to merge in? - uat. C'est le chemin de merge de l'étape 1, écrit sous mergeTargets
5. What is the Salesforce username that will be used for deployments by CI server ? - le nom d'utilisateur de helios-integration, qu'elle vous propose déjà rempli
6. How do you want to provide the SSL certificate? - Generate a self-signed certificate (default). L'autre réponse, signé par une autorité, ne génère rien et se contente d'afficher des instructions
7. Do you want sfdx-hardis to configure the SF CLI External Client App or Connected App on your org ? - oui
8. Which JWT certificate storage mode do you want? - ClientId + decryption key as secret variables + encrypted certificate as file (default). L'autre mode met le certificat lui-même dans un troisième secret et supprime le fichier
9. Please confirm when variables have been set. Celle-ci est un arrêt, et l'étape 5 est ce qu'elle attend. Ne cliquez pas encore sur Validate
10. Puis, après votre confirmation : le nom de l'External Client App, un e-mail de contact, et le profil à pré-autoriser (System Administrator). La liste affiche les noms de profils dans la langue de l'utilisateur de l'org : une org réglée en français liste donc Administrateur système à la place

5. Stocker les deux secrets, puis laisser la commande finir¶

Juste au-dessus de la question 9, le panneau affiche les deux valeurs dont la CI a besoin (2), chacune avec un bouton de copie. Rien ne les réaffiche, ne fermez donc pas le panneau. Le panneau garde chaque question à laquelle vous avez répondu (1), et les fichiers qu'il a écrits sont dans la barre de rapports en bas (3).

Dans votre fork (github.com/my-username/sfdx-hardis-training), ouvrez Settings > Secrets and variables > Actions (1), puis cliquez sur New repository secret (2) :

La page liste les noms des secrets que le repository détient et jamais leurs valeurs (3). Rien, pas même GitHub, ne peut vous remontrer une valeur stockée. C'est toute la raison pour laquelle le panneau vous demande de ne pas le fermer.

Chaque secret est un formulaire : le Name (1), le Secret (2) collé depuis le panneau, puis Add secret (3). Faites-le deux fois :

Le suffixe est le nom de la branche en majuscules. C'est toute la convention, et c'est pourquoi les noms ne sont pas arbitraires.

Cliquez maintenant sur Validate à la question 9, répondez aux trois dernières questions, et laissez la commande créer l'application.

Ce qu'elle a écrit, et où :

La clé privée est chiffrée, avec une passphrase que la commande génère au hasard et que seul votre secret détient. Le repository seul ne suffit pas à s'authentifier, et c'est ce qui rend acceptable de commiter la clé.

6. Vérifier l'autorisation qu'elle a faite pour vous¶

L'étape contre laquelle tout le monde vous met en garde, pré-autoriser l'application, est celle que la commande a déjà faite : l'External Client App qu'elle déploie porte Admin approved users are pre-authorized et le profil que vous avez nommé à la dernière question. Regardez-la une fois, pour savoir où elle est le jour où cela compte.

Dans helios-integration : Setup > External Client App Manager, ouvrez l'application, dont le nom par défaut était sfdxhardisintegration, puis Policies. Permitted Users affiche Admin approved users are pre-authorized, et le profil est listé.

Cela compte à cause du seul chemin où ce n'est pas fait pour vous : si le déploiement de l'application échoue et que la commande retombe sur l'affichage d'instructions manuelles, ces instructions s'arrêtent au téléversement du certificat. Suivez-les à la lettre et la première connexion de CI échoue avec user hasn't approved this consumer, un message exact qui se lit comme un bug.

7. La même chose pour uat, preprod et main¶

Même engrenage, Add/Configure Org, trois fois de plus, une par branche et son org :

Vérifiez l'org deux fois pour main : pointer la production vers la mauvaise org est l'erreur la plus coûteuse disponible dans ce lab. preprod et main sont des orgs Developer Edition, qui se connectent comme le fait la production, et seules les scratch orgs et les sandboxes utilisent test.salesforce.com.

Huit secrets, quatre External Client Apps, quatre clés. Fastidieux une fois, puis plus jamais.

8. Laisser les contributeurs démarrer un hotfix¶

Les contributeurs choisissent où va une User Story dans une liste, et preprod n'y est pas encore.

Ouvrez le panneau DevOps Pipeline, le menu engrenage, Pipeline Settings. Le titre de la page indique Global Pipeline Settings, et le sélecteur de portée (1) indique Global Settings.

Cliquez sur Edit (2), puis sur l'onglet User Stories (3).

Deux champs comptent, et ce sont deux zones de texte distinctes, une valeur par ligne : Available PR/MR target branches (1) et Labels for available PR/MR target branches (2). Rien ne les apparie sinon leur ordre : la ligne 2 de l'une appartient donc à la ligne 2 de l'autre.

Aujourd'hui chacune contient une seule ligne, celle qu'un contributeur choisit depuis le Niveau 1. Ajoutez une deuxième ligne à chacune, à la même position :

uat et main ne sont pas dans cette liste, exprès. Personne ne construit une User Story contre elles : le travail atteint uat par promotion depuis integration, et main par promotion depuis preprod.

Save (3).

9. Dire au panneau ce que le projet utilise désormais¶

config/.sfdx-hardis.yml porte orgAuthenticationMode: secretsOnly, mis là quand le cours vous a tendu le raccourci de l'auth URL. Cela dit au panneau DevOps Pipeline de ne pas chercher de fichiers de clé de certificat, et de ne pas vous avertir quand il n'y en a pas. Il y a des clés maintenant, donc cette ligne est un mensonge, et un panneau à qui on ment cesse de pouvoir vous avertir.

Toujours dans Pipeline Settings, portée Global Settings (1), ouvrez l'onglet Deployment (2).

Org Authentication Mode (3) affiche CI/CD secrets variables only. Cliquez sur Edit (4), changez-le en Encrypted certificate key files, et Save. Désormais le panneau vérifie config/branches/.jwt/<branche>.key pour chaque branche majeure et le dit quand il en manque une.

10. Activer les promotion branches, pour une semaine que vous espérez ne pas avoir¶

Un réglage de plus, sur le même panneau, et c'est le seul de ce lab que vous activez pour quelque chose qui n'est pas encore arrivé.

La plupart des semaines, un release manager promeut une branche entière : tout ce qui est dans uat part vers preprod ensemble, parce que c'est la version que les testeurs ont testée. Certaines semaines, le métier valide une story et pas celle d'à côté, et la date de livraison ne bouge pas. sfdx-hardis a une fonctionnalité en Beta pour cette semaine-là, les promotion branches, et le Lab 3.10 est l'endroit où vous vous en servez.

Toujours dans Pipeline Settings, portée Global Settings, ouvrez l'onglet Danger Zone.

L'onglet s'ouvre sur un avertissement, Use these settings with caution, be sure to understand their impact as they drift from DevOps best practices, et il vaut pour chaque réglage qui s'y trouve, celui-ci compris.

Cliquez sur Edit, activez Enable promotion branches (Beta) (1), puis ajoutez une ligne à Allowed promotion steps (Beta) (2) avec Source branch uat et Target branch preprod. Save.

Le second réglage est exigé par le premier, et c'est une vraie décision plutôt que de la paperasse : il dit qu'un release manager sur ce projet peut assembler un sous-ensemble en entrant dans preprod, l'étape juste avant la production, et nulle part ailleurs. sf hardis:project:promotion:create refuse de tourner tant que la liste est absente, au lieu de deviner que chaque branche majeure peut promouvoir vers toutes les autres.

Rien ne change aujourd'hui. Avec la fonctionnalité active et aucune branche promotion/... dans le repository, la pipeline se comporte exactement comme il y a une minute. Elle est activée maintenant à cause de l'endroit où le réglage doit se trouver au Lab 3.10, et l'étape suivante explique pourquoi ce n'est pas évident.

enablePromotionBranches: true
allowedPromotionSteps:
  - source: uat
    target: preprod

11. Supprimer le raccourci, avant que quoi que ce soit ne prouve quoi que ce soit¶

Dans votre fork (github.com/my-username/sfdx-hardis-training) : **Settings > Secrets and variables

Actions**, trouvez SFDX_AUTH_URL_INTEGRATION et SFDX_AUTH_URL_UAT, et supprimez les deux.

Faites-le maintenant, avant de publier. L'étape d'authentification de chaque job cherche d'abord SFDX_AUTH_URL_<BRANCHE> et s'arrête là dès qu'elle en trouve une. Tant que les deux secrets existent, un job vert ne prouve rien sur vos clés : il s'est connecté à l'ancienne. Une fois qu'ils ont disparu, la seule entrée est celle du JWT, et le prochain job vert est donc la preuve.

12. Publier la configuration par une Pull Request¶

Tout ce que vous avez fait est constitué de fichiers sur votre disque, sur integration : les quatre fichiers de branche, les quatre clés, les branches cibles, le mode d'authentification et les deux réglages des promotion branches. Ils atteignent integration comme toute modification, par une Pull Request aux contrôles verts. La protection de l'étape 3 refuserait tout le reste.

Vous les publiez comme vous avez publié une User Story au Niveau 1, avec les deux mêmes boutons.

Mettez-les sur une branche à part. Vos modifications sont posées sur integration, qui n'accepte rien directement. Ctrl+Shift+P, Git: Create Branch..., et nommez-la config/pipeline-up-to-production. VS Code emporte les fichiers non commités avec vous, rien n'est donc perdu et plus rien n'est sur integration.

Commitez-les. Dans le panneau Source Control, stagez les fichiers de configuration et commitez-les sous Configure the pipeline up to production, exactement comme vous stagiez de la métadonnée au Lab 1.5.

Publiez. Dans le panneau DevOps Pipeline, cliquez sur la carte Save / Publish (1), celle par laquelle chaque story est passée depuis le Lab 1.5. Elle demande la branche cible : integration. Elle commite ce qui reste, lance le nettoyage, et pousse la branche.

Ouvrez la Pull Request. Quand elle se termine, la barre d'actions du bas commence par Create Pull Request (1). Cliquez : l'extension ouvre GitHub sur la page de Pull Request de cette branche, déjà pointée sur integration.

La même barre porte le package.xml généré par la commande (2) et les deployment actions de cette Pull Request (3), comme au Lab 1.6. Cette branche ne change aucune métadonnée, les deux sont donc courts.

Ouvrez la Pull Request dans votre fork. Son contrôle Simulate Deployment to Major Org se connecte à helios-integration sans plus aucun secret d'auth URL à utiliser : ouvrez-le depuis Checks, dépliez Login & Process Deployment, et cherchez sf org login jwt. Cette ligne et un contrôle vert, c'est votre clé qui fonctionne.

Quand les deux contrôles sont verts, mergez avec Merge pull request, pas avec un squash : ce n'est pas une feature, et la configuration doit voyager vers uat, preprod et main avec les promotions, commit par commit (Lab 1.6). Puis Pull dans le panneau Source Control : votre integration récupère la configuration, mergée.

uat, preprod et main prouvent leurs clés la première fois qu'une Pull Request y entre : la promotion vers uat au Lab 3.5, puis preprod et main au Lab 3.6.

sf hardis:project:configure:auth

sf org login jwt \
  --client-id $SFDX_CLIENT_ID_INTEGRATION \
  --jwt-key-file <clé déchiffrée> \
  --username <targetUsername de la config de branche> \
  --instance-url <instanceUrl de la config de branche> \
  --alias integration

availableTargetBranches:
  - integration
  - preprod
availableTargetBranchesLabels:
  - "The shared integration org, where every contributor merges"
  - "Hotfixes on the production version, agreed with the release manager"
orgAuthenticationMode: encryptedCert
enablePromotionBranches: true
allowedPromotionSteps:
  - source: uat
    target: preprod

13. Regarder le diagramme à nouveau¶

Ouvrez le panneau DevOps Pipeline et cliquez sur Refresh. Voici la pipeline que vous avez construit :

1. integration (1), là où les contributeurs mergent, avec la flèche de promotion qui en part
2. uat (2), là où le métier valide
3. preprod (3), la répétition de la production, et le point de départ des hotfixes
4. main (4), la production
5. Les quatre orgs (5), une par branche, dans l'ordre où le travail les traverse

Ce diagramme est désormais la vérité sur ce projet, et ce que vous montrez du doigt quand une partie prenante demande "alors, ça en est où ?". Les boutons + PR sur les flèches sont les Pull Requests de promotion, et le Lab 3.5 est la première fois que vous en cliquez un.

Ce que vous devez voir¶

• Quatre règles de protection de branche dans Settings > Branches de votre fork, integration, uat, preprod et main, chacune exigeant une Pull Request et les deux contrôles
• config/branches/ sur integration contenant quatre fichiers et quatre fichiers .jwt/*.key
• Huit secrets dans votre fork, dont aucun n'est une auth URL
• Votre Pull Request de configuration mergée dans integration, avec sf org login jwt dans le log de son contrôle
• Le panneau DevOps Pipeline avec quatre colonnes et aucun avertissement de clé manquante
• enablePromotionBranches et une étape autorisée dans la Danger Zone de Pipeline Settings, qui ne font rien jusqu'au Lab 3.10

Vérifiez votre travail¶

Welcome page > Training: Level 3 > Check my work, puis choisissez le Lab 3.1.

Pour aller plus loin¶

• Guide d'installation
• Configurer l'authentification de la CI
• Authentification GitHub Actions
• Récupérer une org existante

Suite : Lab 3.2 - Relire et merger la Pull Request d'un contributeur

Questions and comments