est exécuté comme un programme Groovy, certains appels de fonctions spéciaux appelés étapes réalisant des opérations spécifiques à Jenkins. Dans cet exemple, l'étape parallel est définie dans ce plugin, tandis que node, retry, checkout et sh sont définis dans d'autres plugins de la suite Pipeline. La variable globale scm est définie dans le plugin Pipeline Multibranch.

Le script Groovy est compilé en une classe nommée WorkflowScript, c'est donc ce nom qui apparaît dans les traces de pile au lieu du nom de fichier du script (par exemple Jenkinsfile).

Contrairement à un programme Groovy classique exécuté depuis une ligne de commande, l'état complet du programme d'un build Pipeline est enregistré sur disque à chaque fois qu'une opération asynchrone est effectuée, ce qui inclut la plupart des étapes Pipeline. Jenkins peut être redémarré pendant qu'un build est en cours d'exécution, et reprendra l'exécution du programme là où il s'était arrêté. Ce mécanisme n'est pas conçu pour être efficace et doit donc être limité au code « colle » de haut niveau directement lié aux fonctionnalités de Jenkins ; la logique de build propre à votre projet doit être exécutée à partir de programmes externes sur un nœud de build, dans une étape sh ou bat.

Limitations connues

L'épopée Pipeline Groovy dans JIRA couvre certaines limitations connues de l'interpréteur Groovy. Ces problèmes proviennent du fait que Pipeline ne peut pas exécuter Groovy directement, mais doit intercepter chaque opération pour enregistrer l'état du programme.

L'épopée Pipeline Sandbox couvre les problèmes liés au bac à sable Groovy utilisé pour empêcher les scripts Pipeline malveillants de prendre le contrôle de Jenkins. Les scripts exécutés avec le bac à sable désactivé peuvent appeler directement les API internes de Jenkins, ce qui peut être une solution de contournement utile pour les fonctionnalités d'étapes manquantes, mais pour des raisons de sécurité, seuls les administrateurs peuvent approuver de tels scripts.

L'épopée Pipeline Snippet Generator couvre les problèmes liés à l'outil utilisé pour fournir des exemples de syntaxe d'étapes à partir de formulaires de configuration en direct.

Historique

Ce plugin s'appelait auparavant « Workflow CPS plugin » ou « Workflow Groovy Plugin ». Il porte donc l'artifactId Maven workflow-cps, et non pipeline-groovy.

Conception technique

Le plugin utilise la bibliothèque Groovy CPS pour implémenter une transformation de style par passage de continuation sur le programme lors de sa compilation. Le compilateur Groovy standard est utilisé pour créer l'AST, mais la génération du bytecode est interceptée par un CompilationCustomizer qui remplace la plupart des opérations par des variantes qui lèvent une « erreur » spéciale, CpsCallableInvocation. Celle-ci est ensuite interceptée par le moteur, qui utilise les informations qu'elle contient (comme les arguments sur le point d'être passés à un appel de méthode) pour transmettre le contrôle à la continuation suivante.

Les scripts Pipeline peuvent marquer des méthodes désignées avec l'annotation @NonCPS. Ces méthodes sont alors compilées normalement (sauf pour les vérifications de sécurité du bac à sable) et se comportent donc en grande partie comme des méthodes « binaires » de la plateforme Java, de l'environnement d'exécution Groovy, ou du code de Jenkins ou de ses plugins. Les méthodes @NonCPS peuvent utiliser en toute sécurité des objets non Serializable comme variables locales, mais elles ne doivent pas accepter de paramètres non sérialisables ni retourner ou stocker de valeurs non sérialisables. Vous ne pouvez pas appeler de méthodes régulières (transformées par CPS) ni d'étapes Pipeline depuis une méthode @NonCPS ; il est donc préférable de les utiliser pour effectuer certains calculs avant de renvoyer un résumé au script principal. Notez en particulier que les @Override de méthodes définies dans des classes binaires, telles que Object.toString(), devraient en général être marqués @NonCPS car ce sera généralement du code binaire qui les appellera.

Certains types d'objets ne sont intrinsèquement pas sûrs à sérialiser en tant que tels, mais nous souhaitons conserver une référence vers eux dans le graphe du programme. Un exemple est l'Executor (~ emplacement d'exécuteur sur un nœud intégré ou un agent), qui fait partie du contexte passé par une étape node à toute étape de son bloc, en particulier sh/bat. Pipeline utilise l'API Pickle pour substituer des versions sûres pour la sérialisation de ces objets. Lorsqu'un WorkflowRun est chargé depuis le disque après un redémarrage, l'état du programme est désérialisé et les pickles sont désérialisés (« réhydratés ») en parallèle. Lorsque tous les pickles sont désérialisés avec succès et que les objets résultants sont replacés dans l'état du programme, le programme recommence à s'exécuter et StepExecution.onResume est appelé pour restaurer les minuteries et autres éléments.

Toute la logique du programme est exécutée à l'intérieur d'un « thread CPS VM », qui n'est qu'un pool de threads Java capable d'exécuter des méthodes binaires et de déterminer quelle continuation exécuter ensuite. L'étape parallel utilise des « threads verts » (également appelés multitâche coopératif) : elle enregistre des noms de threads logiques (~ branches) pour diverses actions, mais ne les exécute pas littéralement simultanément. Le programme peut sembler effectuer des tâches en parallèle, mais uniquement parce que la plupart des étapes s'exécutent de manière asynchrone, pendant que le thread VM est inactif, et qu'elles peuvent se chevaucher dans le temps. Aucun thread Java n'est consommé, sauf pendant les intervalles généralement brefs où le code Groovy est réellement exécuté sur le thread VM. Le widget d'exécuteurs n'affiche une entrée pour l'exécuteur « flyweight » sur le nœud intégré que lorsque le thread VM est occupé ; normalement, il est masqué.