Como administrador o desarrollador de DevOps, puede crear scripts personalizados que amplíen la capacidad de Code Stream. Con un script, puede integrar Code Stream con sus propias API y herramientas de integración continua (Continuous Integration, CI) y distribución continua (Continuous Delivery, CD) que compilan, prueban e implementan las aplicaciones. Los scripts personalizados son especialmente útiles si no se exponen las API de aplicaciones de manera pública.

El script personalizado puede hacer casi todo lo necesario para integrarse con las herramientas de compilación, pruebas e implementación. Por ejemplo, puede utilizarse con el área de trabajo de la canalización para brindar soporte a tareas de CI que compilan y prueban la aplicación, así como a tareas de CD que implementan la aplicación. Puede enviar un mensaje a Slack cuando finaliza una canalización, etc.

Escriba el script personalizado en uno de los lenguajes compatibles. En el script, incluya la lógica empresarial y defina las entradas y las salidas. Los tipos de salida pueden ser números, cadenas, texto y contraseñas. Puede crear varias versiones de un script personalizado con diferentes entradas, salidas y lógicas empresariales.

Haga que la canalización ejecute una versión del script en una tarea personalizada. Los scripts que cree residirán en la instancia de Code Stream.

Cuando una canalización utiliza una integración personalizada y se intenta eliminarla, aparece un mensaje de error que indica que no se puede eliminar.

Al eliminar una integración personalizada, se eliminan todas las versiones de su script personalizado. Si tiene una canalización existente con una tarea personalizada que utiliza cualquier versión del script, se producirá un error en esa canalización. Para asegurarse de que no se produzcan errores en las canalizaciones existentes, puede descartar y retirar la versión del script que ya no desee utilizar. Si ninguna canalización utiliza esa versión, puede eliminarla.

Tabla 1. Qué hacer después de escribir el script personalizado
Qué hacer... Más información sobre esta acción...

Agregue una tarea personalizada a la canalización.

La tarea personalizada:

  • Se ejecuta en el mismo contenedor que otras tareas de CI de la canalización.
  • Incluye variables de entrada y de salida que el script rellena antes de que la canalización ejecute la tarea personalizada.
  • Admite varios tipos de datos y varios tipos de metadatos que define como entradas y salidas en el script.

Seleccione el script en la tarea personalizada.

Declare las propiedades de entrada y de salida en el script.

Guarde la canalización y, a continuación, habilítela y ejecútela.

Cuando se ejecuta la canalización, la tarea personalizada llama a la versión del script especificado y ejecuta la lógica empresarial que contiene, lo que integra la herramienta de compilación, pruebas e implementación con Code Stream.

Una vez que se ejecute la canalización, observe las ejecuciones.

Compruebe que la canalización ha producido los resultados esperados.

En este ejemplo, se crea una integración personalizada que conecta Code Stream con la instancia de Slack y publica un mensaje en un canal de Slack.

Requisitos previos

  • Para escribir un script personalizado, asegúrese de tener uno de estos lenguajes: Python 2, Python 3, Node.js o cualquiera de estos lenguajes de shell: Bash, sh o zsh.
  • Genere una imagen de contenedor mediante el tiempo de ejecución de Node.js o Python instalado.

Procedimiento

  1. Cree la integración personalizada.
    1. Haga clic en Integraciones personalizadas > Nuevo e introduzca un nombre pertinente.
    2. Seleccione el entorno de tiempo de ejecución que prefiera.
    3. Haga clic en Crear.
      Se abrirá el script mostrando el código, que incluye el entorno de tiempo de ejecución requerido. Por ejemplo, runtime: "nodejs". El script debe incluir el tiempo de ejecución que la imagen de Builder usa, de forma que la tarea personalizada que agregue a la canalización se realice correctamente cuando la canalización se ejecute. De lo contrario, se producirá un error en la tarea personalizada.
    Las principales áreas de los YAML de integración personalizada incluyen el tiempo de ejecución, el código, las propiedades de entrada y las propiedades de salida. Este procedimiento explica diversos tipos y sintaxis.
    Claves de YAML de integración personalizada Descripción
    runtime

    Entorno de tiempo de ejecución de la tarea en el que Code Stream ejecuta el código, que puede ser una de estas cadenas sin distinción entre mayúsculas y minúsculas:

    • nodejs
    • python2
    • python3
    • shell

    Si no se proporciona nada, se asume el valor predeterminado de shell.

    code Lógica empresarial personalizada que se ejecutará como parte de la tarea personalizada.
    inputProperties Matriz de propiedades de entrada que se capturarán como parte de la configuración de la tarea personalizada. Por lo general, estas propiedades se utilizan en el código.
    outputProperties Matriz de propiedades de salida que puede exportar de la tarea personalizada para propagarla a la canalización.
  2. Declare las propiedades de entrada en el script mediante los tipos de datos y los metadatos disponibles.
    Las propiedades de entrada se transfieren como contexto al script en la sección code: del YAML.
    Claves de entrada de YAML de tareas personalizadas Descripción Obligatorio
    type Tipos de entrada para representar:
    • Texto
    • Área de texto
    • Número
    • Casilla de verificación
    • Contraseña
    • Selección
    name Nombre o cadena de entrada a la tarea personalizada, que se inyecta en el código YAML de integración personalizada. Debe ser único para cada propiedad de entrada definida para una integración personalizada.
    title Etiqueta de la cadena de texto de la propiedad de entrada de la tarea personalizada en el lienzo del modelo de canalización. Si se deja en blanco, se utiliza name de forma predeterminada. No
    required Determina si un usuario debe introducir la propiedad de entrada al configurar la tarea personalizada. Establézcalo en true o false. Cuando el valor es true, si un usuario no proporciona un valor al configurar la tarea personalizada en el lienzo de canalización, el estado de la tarea permanece como sin configurar. No
    placeHolder Texto predeterminado para el área de entrada de propiedades de entrada cuando no hay ningún valor. Se asigna al atributo del marcador de posición HTML. Solo se admite para ciertos tipos de propiedad de entrada. No
    defaultValue Valor predeterminado que rellena el área de entrada de la propiedad de entrada cuando la tarea personalizada se representa en la página del modelo de canalización. No
    bindable Determina si la propiedad de entrada acepta variables de signo de dólar al modelar la tarea personalizada en el lienzo de canalización. Agrega el indicador $ junto al título. Solo se admite para ciertos tipos de propiedad de entrada. No
    labelMessage Cadena que actúa como información sobre herramientas de ayuda para los usuarios. Agrega un icono de información sobre herramientas i junto al título de entrada. No
    enum Toma una matriz de valores que muestra las opciones de la propiedad de entrada seleccionada. Solo se admite para ciertos tipos de propiedad de entrada.

    Cuando un usuario selecciona una opción y la guarda para la tarea personalizada, el valor de inputProperty corresponde a este valor y aparece en el modelado de tareas personalizado.

    Por ejemplo, el valor 2015.

    • 2015
    • 2016
    • 2017
    • 2018
    • 2019
    • 2020
    No
    options Toma una matriz de objetos usando optionKey y optionValue.
    • optionKey. Valor propagado a la sección de código de la tarea.
    • optionValue. Cadena que muestra la opción en la interfaz de usuario.

    Solo se admite para ciertos tipos de propiedad de entrada.

    Opciones:

    optionKey: key1. Cuando se selecciona y se guarda para la tarea personalizada, el valor de inputProperty correspondería a key1 en la sección de código.

    optionValue: 'Etiqueta para 1'. Valor para mostrar de key1 en la interfaz de usuario. No aparece en ningún otro lugar para la tarea personalizada.

    optionKey: key2

    optionValue: 'Etiqueta para 2'

    optionKey: key3

    optionValue: 'Etiqueta para 3'

    No
    minimum Acepta un número que actúa como el valor mínimo que es válido para esta propiedad de entrada. Solo se admite para la propiedad de entrada del tipo de número. No
    maximum Acepta un número que actúa como el valor máximo que es válido para esta propiedad de entrada. Solo se admite para la propiedad de entrada del tipo de número. No
    Tabla 2. Tipos de datos y metadatos admitidos para scripts personalizados
    Tipos de datos admitidos Metadatos admitidos para la entrada
    • String
    • Text
    • List: como una lista de cualquier tipo
    • Map: como map[string]any
    • Secure: se representa como un cuadro de texto de contraseña, cifrado cuando se guarda la tarea personalizada
    • Number
    • Boolean: se muestra como cuadros de texto
    • URL: igual que una cadena, con validación adicional
    • Botón de selección o de radio
    • type: un tipo como String | Text...
    • default: valor predeterminado
    • options: lista o asignación de opciones que se usará con un botón de selección o de radio
    • min: valor o tamaño mínimo
    • max: valor o tamaño máximo
    • title: nombre detallado del cuadro de texto
    • placeHolder: marcador de posición de la interfaz de usuario
    • description: se convierte en información sobre herramientas
    Por ejemplo:
    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. Declare las propiedades de salida del script.
    El script captura las propiedades de salida de la sección code: de la lógica empresarial del script, donde declara el contexto de la salida.
    Cuando se ejecuta la canalización, puede introducir el código de respuesta para la salida de la tarea. Por ejemplo, 200.
    Las claves que Code Stream admite para cada outputProperty.
    key Descripción
    type Actualmente incluye un solo valor de label.
    name Clave que emite el bloque de código de YAML de integración personalizada.
    title Etiqueta en la interfaz de usuario que muestra outputProperty.
    Por ejemplo:
    outputProperties:
      - name: statusCode
        type: label
        title: Status Code
  4. Para interactuar con la entrada y la salida del script personalizado, obtenga una propiedad de entrada o establezca una propiedad de salida mediante context.
    Para una propiedad de entrada: (context.getInput("key"))
    Para una propiedad de salida: (context.setOutput("key", "value"))
    Para Node.js:
    var context = require("./context.js")
    var message = context.getInput("message");
    //Your Business logic
    context.setOutput("statusCode", 200);
    Para Python:
    from context import getInput, setOutput
    message = getInput('message')
    //Your Business logic
    setOutput('statusCode', '200')
    
    Para Shell:
    # Input, Output properties are environment variables
    echo ${message} # Prints the input message
    //Your Business logic
    export statusCode=200 # Sets output property statusCode
    
  5. En la sección code:, declare toda la lógica empresarial de la integración personalizada.
    Por ejemplo, con el entorno de tiempo de ejecución de 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. Antes de crear una versión del script de integración personalizado y publicarla, descargue el archivo de contexto para Python o Node.js y pruebe la lógica empresarial que incluyó en el script.
    1. Coloque el cursor en el script y haga clic en el botón de archivo de contexto situado en la parte superior del lienzo. Por ejemplo, si el script se encuentra en Python, haga clic en CONTEXT.PY.
    2. Modifique el archivo y guárdelo.
    3. En el sistema de desarrollo, ejecute y pruebe su script personalizado con la ayuda del archivo de contexto.
  7. Aplique una versión al script de integración personalizado.
    1. Haga clic en Versión.
    2. Introduzca la información de la versión.
    3. Haga clic en Versión de publicación para poder seleccionar el script en la tarea personalizada.
    4. Para crear la versión, haga clic en Crear.
      Crear versiones del script de integración personalizado.
  8. Para guardar el script, haga clic en Guardar.
  9. En la canalización, configure el área de trabajo.
    1. Haga clic en la pestaña Área de trabajo.
    2. Seleccione el host de Docker y la dirección URL de la imagen de Builder.
      Crear una integración personalizada.
  10. Agregue una tarea personalizada a la canalización y configúrela.
    1. Haga clic en la pestaña Modelo.
    2. Agregue una tarea, seleccione el tipo como Personalizado e introduzca un nombre pertinente.
    3. Seleccione el script de integración personalizado y la versión.
    4. Para mostrar un mensaje personalizado en Slack, introduce el texto del mensaje.
      Cualquier texto que introduzca reemplaza el valor defaultValue en el script de integración personalizado. Por ejemplo:
      Agregar y configurar una tarea personalizada en la canalización.
  11. Guarde y habilite la canalización.
    1. Haga clic en Guardar.
    2. En la pestaña Canalización, haga clic en Habilitar canalización para que el círculo se mueva hacia la derecha.
  12. Ejecute la canalización.
    1. Haga clic en Ejecutar.
    2. Observe la ejecución de la canalización.
    3. Confirme que la salida incluya el código de estado, el código de respuesta, el estado y la salida declarada previstos.
      Ha definido statusCode como una propiedad de salida. Por ejemplo, si statusCode tiene un valor de 200 puede indicar una publicación de Slack correcta, y responseCode con un valor de 0 puede indicar que el script se ha completado correctamente sin errores.
    4. Para confirmar la salida en los registros de ejecución, haga clic en Ejecuciones, haga clic en el vínculo a la canalización, haga clic en la tarea y observe los datos registrados. Por ejemplo:
      Ver la salida de la tarea para la integración personalizada.
  13. Si se produce un error, solucione el problema y vuelva a ejecutar la canalización.
    Por ejemplo, si falta un archivo o un módulo en la imagen base, debe crear otra imagen base que incluya el archivo que falta. A continuación, proporcione el archivo de Docker e inserte la imagen a través de la canalización.

Resultados

Enhorabuena. Se creó un script de integración personalizada que conecta Code Stream con la instancia de Slack y publica un mensaje en un canal de Slack.

Qué hacer a continuación

Siga creando integraciones personalizadas para permitir el uso de tareas personalizadas en las canalizaciones, de modo que pueda ampliar la capacidad de Code Stream en la automatización del ciclo de vida de publicación de software.