En tant qu'administrateur ou développeur DevOps, vous pouvez créer des scripts personnalisés qui étendent la capacité de Code Stream. Avec votre script, vous pouvez intégrer Code Stream à vos propres outils et API d'intégration continue (CI) et de prestation continue (CD) qui génèrent, testent et déploient vos applications. Les scripts personnalisés sont particulièrement utiles si vous n'exposez pas publiquement vos API d'application.

Votre script personnalisé peut effectuer presque toutes les opérations nécessaires à une intégration à vos outils de génération, de test et de déploiement. Par exemple, il peut utiliser l'espace de travail de votre pipeline pour prendre en charge les tâches CI qui génèrent et testent votre application, ainsi que les tâches CD qui la déploient. Il peut envoyer un message à Slack lorsqu'un pipeline se termine, et bien plus encore.

Vous écrivez votre script personnalisé dans l'un des langages pris en charge. Dans le script, vous incluez votre logique métier, et définissez des entrées et des sorties. Les types de sorties peuvent inclure un nombre, une chaîne, un texte et un mot de passe. Vous pouvez créer plusieurs versions d'un script personnalisé avec une logique d'activité, une entrée et une sortie différentes.

Votre pipeline exécute une version de votre script dans une tâche personnalisée. Les scripts que vous créez résident dans votre instance de Code Stream.

Lorsqu'un pipeline utilise une intégration personnalisée et que vous tentez de supprimer cette intégration, un message d'erreur s'affiche indiquant que vous ne pouvez pas la supprimer.

La suppression d'une intégration personnalisée supprime toutes les versions de votre script personnalisé. Si vous disposez d'un pipeline existant incluant une tâche personnalisée qui utilise une version du script, ce pipeline va échouer. Pour vous assurer que les pipelines existants n'échouent pas, vous pouvez déconseiller et retirer la version de votre script que vous ne souhaitez plus utiliser. Si aucun pipeline n'utilise cette version, vous pouvez la supprimer.

Tableau 1. Actions postérieures à la rédaction de votre script personnalisé
Actions… Plus d’informations sur cette action…

Ajout d'une tâche personnalisée à votre pipeline.

La tâche personnalisée :

  • s'exécute sur le même conteneur que les autres tâches CI de votre pipeline.
  • inclut les variables d'entrée et de sortie que votre script remplit avant l'exécution de la tâche personnalisée par le pipeline.
  • prend en charge plusieurs types de données et différents types de métadonnées que vous définissez comme entrées et sorties dans votre script.

Sélection de votre script dans la tâche personnalisée.

Vous déclarez les propriétés d'entrée et de sortie dans le script.

Enregistrement de votre pipeline, avant activation et exécution.

Lorsque le pipeline s'exécute, la tâche personnalisée appelle la version du script spécifié et y exécute la logique métier, ce qui intègre votre outil de génération, de test et de déploiement à Code Stream.

Une fois votre pipeline exécuté, observation des exécutions.

Vérifiez que le pipeline a fourni les résultats attendus.

Lorsque vous utilisez une tâche personnalisée qui appelle une version d'intégration personnalisée, vous pouvez inclure des variables d'environnement personnalisées sous forme de paires nom-valeur dans l'onglet Espace de travail du pipeline. Lorsque l'image de générateur crée le conteneur d'espace de travail qui exécute la tâche CI et déploie votre image, Code Stream transmet les variables d'environnement à ce conteneur.

Par exemple, lorsque votre instance de Code Stream nécessite un proxy Web et que vous utilisez un hôte Docker pour créer un conteneur pour une intégration personnalisée, Code Stream exécute le pipeline et transmet les variables de configuration de proxy Web à ce conteneur.

Tableau 2. Exemple de paires nom-valeur de variable d'environnement
Nom Valeur
HTTPS_PROXY http://10.0.0.255:1234
https_proxy http://10.0.0.255:1234
NO_PROXY 10.0.0.32, *.dept.vsphere.local
no_proxy 10.0.0.32, *.dept.vsphere.local
HTTP_PROXY http://10.0.0.254:1234
http_proxy http://10.0.0.254:1234
PATH /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

Les paires nom-valeur s'affichent dans l'interface utilisateur de la manière suivante :

Cet exemple crée une intégration personnalisée qui connecte Code Stream à votre instance Slack et publie un message sur un canal Slack.

Conditions préalables

  • Pour écrire votre script personnalisé, vérifiez que vous disposez de l'un des langages suivantes : Python 2, Python 3, Node.js ; ou de l'un des langages Shell suivants : bash, sh ou zsh.
  • Générez une image de conteneur à l'aide du composant d'exécution Node.js ou Python installé.

Procédure

  1. Créez l'intégration personnalisée.
    1. Cliquez sur Intégrations personnalisées > Nouveau et entrez un nom pertinent.
    2. Sélectionnez l'environnement d'exécution préféré.
    3. Cliquez sur Créer.
      Votre script s'ouvre et affiche le code, qui inclut l'environnement d'exécution requis. Par exemple, runtime: "nodejs". Le script doit inclure le composant d'exécution que l'image du générateur utilise, afin que la tâche personnalisée que vous ajoutez à votre pipeline aboutisse lorsque le pipeline s'exécute. Sinon, la tâche personnalisée échoue.
    Les principaux aspects de votre intégration personnalisée YAML incluent l'exécution, le code, les propriétés d'entrée et les propriétés de sortie. Cette procédure explique différents types et la syntaxe.
    Clés YAML d'intégration personnalisée Description
    runtime

    Environnement d'exécution des tâches où Code Stream exécute le code, qui peut être l'une de ces chaînes insensibles à la casse :

    • nodejs
    • python2
    • python3
    • shell

    Si rien n'est indiqué, shell est la valeur par défaut supposée.

    code Logique métier personnalisée à exécuter dans le cadre de la tâche personnalisée.
    inputProperties Tableau de propriétés d'entrée à capturer dans le cadre de la configuration de la tâche personnalisée. Ces propriétés sont normalement utilisées dans le code.
    outputProperties Tableau de propriétés de sortie que vous pouvez exporter à partir de la tâche personnalisée à propager au pipeline.
  2. Déclarez les propriétés d'entrée dans votre script en utilisant les types de données et les métadonnées disponibles.
    Les propriétés d'entrée sont transmises sous forme de contexte à votre script dans la section code: du fichier YAML.
    Touches d'entrée YAML de tâche personnalisée Description Requis
    type Types d'entrée à rendre :
    • text
    • textarea
    • number
    • checkbox
    • password
    • select
    Oui
    name Nom ou chaîne de l'entrée de la tâche personnalisée, qui est injectée dans le code YAML d'intégration personnalisée. Doit être unique pour chaque propriété d'entrée définie pour une intégration personnalisée. Oui
    title Libellé de chaîne de texte de la propriété d'entrée pour la tâche personnalisée sur le canevas du modèle de pipeline. S'il est laissé vide, name est utilisé par défaut. Non
    required Détermine si un utilisateur doit entrer la propriété d'entrée lorsqu'il configure la tâche personnalisée. Définissez sur true ou false. Lorsque la valeur est true, si un utilisateur ne fournit pas de valeur lorsqu'il configure la tâche personnalisée sur le canevas du pipeline, l'état de la tâche reste non configuré. Non
    placeHolder Texte par défaut pour la zone d'entrée de la propriété d'entrée lorsqu'aucune valeur n'est présente. Correspond à l'attribut html placeholder. Uniquement pris en charge pour certains types de propriétés d'entrée. Non
    defaultValue Valeur par défaut qui renseigne la zone d'entrée de la propriété d'entrée lorsque la tâche personnalisée s'affiche sur la page du modèle de pipeline. Non
    bindable Détermine si la propriété d'entrée accepte les variables de symbole dollar lors de la modélisation de la tâche personnalisée sur le canevas du pipeline. Ajoute l'indicateur $ en regard du titre. Uniquement pris en charge pour certains types de propriétés d'entrée. Non
    labelMessage Chaîne qui agit comme une info-bulle d'aide pour les utilisateurs. Ajoute une icône d'info-bulle i en regard du titre d'entrée. Non
    enum Prend un tableau de valeurs qui affiche les options de sélection de propriétés d'entrée. Uniquement pris en charge pour certains types de propriétés d'entrée.

    Lorsqu'un utilisateur sélectionne une option et l'enregistre pour la tâche personnalisée, la valeur de inputProperty correspond à cette valeur et figure dans la modélisation de tâche personnalisée.

    Par exemple, la valeur 2015.

    • 2015
    • 2016
    • 2017
    • 2018
    • 2019
    • 2020
    Non
    options Prend un tableau d'objets en utilisant optionKey et optionValue.
    • optionKey. Valeur propagée à la section code de la tâche.
    • optionValue. Chaîne qui affiche l'option dans l'interface utilisateur.

    Uniquement pris en charge pour certains types de propriétés d'entrée.

    Options :

    optionKey : key1. Lorsque cette option est sélectionnée et enregistrée pour la tâche personnalisée, la valeur de inputProperty correspond à key1 dans la section code.

    optionValue : « Label for 1 ». Valeur d'affichage de key1 dans l'interface utilisateur et ne figure nulle part ailleurs pour la tâche personnalisée.

    optionKey : key2

    optionValue : « Label for 2 »

    optionKey : key3

    optionValue : « Label for 3 »

    Non
    minimum Prend un nombre qui agit comme la valeur minimale qui est valide pour cette propriété d'entrée. Uniquement pris en charge pour la propriété d'entrée de type nombre. Non
    maximum Prend un nombre qui agit comme la valeur maximale valide pour cette propriété d'entrée. Uniquement pris en charge pour la propriété d'entrée de type nombre. Non
    Tableau 3. Types de données et métadonnées pris en charge pour les scripts personnalisés
    Types de données pris en charge Métadonnées prises en charge pour l'entrée
    • Chaîne
    • Texte
    • Liste : sous forme de liste de n'importe quel type
    • Carte : sous la forme map[chaîne]any
    • Sécurisé : rendu sous forme de zone de texte pour mot de passe, chiffrée lorsque vous enregistrez la tâche personnalisée
    • Nombre
    • Booléen : s'affiche sous forme de zones de texte
    • URL : identique au type Chaîne, avec validation supplémentaire
    • Sélection, case d'option
    • type : Une chaîne | Texte...
    • valeur par défaut : valeur par défaut
    • options : liste ou carte d'options à utiliser avec la sélection ou la case d'option
    • min. : valeur ou taille minimale
    • max. : valeur ou taille maximale
    • titre : nom détaillé de la zone de texte
    • espace réservé : espace réservé dans l'interface utilisateur
    • description : devient une info-bulle
    Par exemple :
    inputProperties:
            - name: message
              type: text
              title: Message
              placeHolder: Message for Slack Channel
              defaultValue: Hello Slack
              bindable: true
              labelInfo: true
              labelMessage: This message is posted to the Slack channel link provided in the code
    
  3. Déclarez les propriétés de sortie dans votre script.
    Le script capture les propriétés de sortie à partir de la section de la logique métier code: de votre script, dans laquelle vous déclarez le contexte de la sortie.
    Lorsque le pipeline s'exécute, vous pouvez entrer le code de réponse correspondant au résultat de la tâche. Par exemple, 200.
    Clés que Code Stream prend en charge pour chaque outputProperty.
    key Description
    type Inclut actuellement une seule valeur de label.
    name Clé que le bloc de code de l'intégration personnalisée YAML émet.
    title Étiquette dans l'interface utilisateur qui affiche outputProperty.
    Par exemple :
    outputProperties:
      - name: statusCode
        type: label
        title: Status Code
  4. Pour interagir avec l'entrée et la sortie de votre script personnalisé, obtenez une propriété d'entrée ou définissez une propriété de sortie en utilisant context.
    Pour une propriété d'entrée : (context.getInput("key"))
    Pour une propriété de sortie : (context.setOutput("key", "value"))
    Pour Node.js :
    var context = require("./context.js")
    var message = context.getInput("message");
    //Your Business logic
    context.setOutput("statusCode", 200);
    Pour Python :
    from context import getInput, setOutput
    message = getInput('message')
    //Your Business logic
    setOutput('statusCode', '200')
    
    Pour Shell :
    # Input, Output properties are environment variables
    echo ${message} # Prints the input message
    //Your Business logic
    export statusCode=200 # Sets output property statusCode
    
  5. Dans la section code:, déclarez l'ensemble de la logique métier pour votre intégration personnalisée.
    Par exemple, avec l'environnement d'exécution Node.js :
    code: |
        var https = require('https');
        var context = require("./context.js")
        
        //Get the entered message from task config page and assign it to message var
        var message = context.getInput("message");
        var slackPayload = JSON.stringify(
            {
                text: message
            });
    
        const options = {
            hostname: 'hooks.slack.com',
            port: 443,
            path: '/YOUR_SLACK_WEBHOOK_PATH',
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Content-Length': Buffer.byteLength(slackPayload)
            }
        };
        
        // Makes a https request and sets the output with statusCode which 
        // will be displayed in task result page after execution
        const req = https.request(options, (res) => {
            context.setOutput("statusCode", res.statusCode);
        });
    
        req.on('error', (e) => {
            console.error(e);
        });
        req.write(slackPayload);
        req.end();
    
  6. Avant de procéder au contrôle de la version et à la publication de votre script d'intégration personnalisé, téléchargez le fichier de contexte pour Python ou Node.js, et testez la logique d'activité que vous avez incluse dans votre script.
    1. Placez le pointeur dans le script, puis cliquez sur le bouton Fichier de contexte en haut du canevas. Par exemple, si votre script est écrit dans le langage de programmation Python, cliquez sur CONTEXT.PY.
    2. Modifiez le fichier et enregistrez-le.
    3. Sur votre système de développement, exécutez et testez votre script personnalisé à l'aide du fichier de contexte.
  7. Appliquez une version à votre script d'intégration personnalisé.
    1. Cliquez sur Version.
    2. Entrez les informations relatives à la version.
    3. Cliquez sur Version pour pouvoir sélectionner le script dans votre tâche personnalisée.
    4. Pour créer la version, cliquez sur Créer.
      Gestion des versions de votre script d'intégration personnalisé.
  8. Pour enregistrer le script, cliquez sur Enregistrer.
  9. Dans votre pipeline, configurez l'espace de travail.
    1. Cliquez sur l'onglet Espace de travail.
    2. Sélectionnez l'hôte Docker et l'URL de l'image du générateur.
      Création d'une intégration personnalisée.
  10. Ajoutez une tâche personnalisée à votre pipeline et configurez-la.
    1. Cliquez sur l'onglet Modèle.
    2. Ajoutez une tâche, sélectionnez le type personnalisé et entrez un nom pertinent.
    3. Sélectionnez votre script d'intégration personnalisé et sa version.
    4. Pour afficher un message personnalisé dans Slack, entrez le texte du message.
      Tout texte que vous entrez remplace la defaultValue dans votre script d'intégration personnalisé. Par exemple :
      Ajout et configuration d'une tâche personnalisée dans votre pipeline.
  11. Enregistrez et activez votre pipeline.
    1. Cliquez sur Enregistrer.
    2. Dans l'onglet Pipeline, cliquez sur Activer le pipeline afin que le cercle se déplace vers la droite.
  12. Exécutez votre pipeline.
    1. Cliquez sur Exécuter.
    2. Observez l'exécution du pipeline.
    3. Vérifiez que la sortie inclut le code d'état, le code de réponse, l'état et le résultat déclaré attendus.
      Vous avez défini statusCode comme propriété de sortie. Par exemple, un statusCode de 200 peut indiquer une publication Slack réussie et un responseCode de 0 peut indiquer la réussite sans erreur du script.
    4. Pour vérifier le résultat dans les journaux d'exécution, cliquez sur Exécutions, sur le lien vers votre pipeline, puis sur la tâche, et examinez les données consignées. Par exemple :
      Affichage du résultat d'une tâche lors d'une intégration personnalisée.
  13. Si une erreur se produit, résolvez le problème et réexécutez le pipeline.
    Par exemple, si un fichier ou un module de l'image de base est manquant, vous devez créer une autre image de base qui inclut le fichier manquant. Ensuite, fournissez le fichier Docker et transmettez l'image via le pipeline.

Résultats

Félicitations ! Vous avez créé un script d'intégration personnalisé qui connecte Code Stream à votre instance de Slack et publie un message sur un canal Slack.

Que faire ensuite

Continuez à créer des intégrations personnalisées pour prendre en charge l'utilisation de tâches personnalisées dans vos pipelines, afin de pouvoir étendre la capacité de Code Stream dans l'automatisation du cycle de vie de votre version logicielle.