Creación de una acción de GitHub personalizada

Completado

Acciones de GitHub es una característica eficaz que ayuda a pasar del código a la nube desde la comodidad de un repositorio propio. Aquí, obtendrá información sobre los diferentes tipos de acciones de GitHub y los metadatos, la sintaxis y los comandos de flujo de trabajo para crear acciones de GitHub personalizadas.

Tipos de acciones de GitHub

Las acciones son tareas individuales que puede usar para personalizar los flujos de trabajo de desarrollo. Puede crear acciones propias si escribe código personalizado que interactúe con el repositorio para realizar tareas personalizadas o si utiliza acciones que la comunidad de GitHub comparte. Al navegar por varias acciones, observará que hay tres tipos diferentes: acciones de contenedor de Docker, acciones de JavaScript y acciones de paso de ejecución compuesto. Ahora se analizará cada tipo de acción con más detalle.

Acciones de contenedor de Docker

Los contenedores de Docker empaquetan el entorno con el código de Acciones de GitHub. Esto significa que la acción se ejecuta en un entorno coherente y confiable porque todas sus dependencias están dentro de ese contenedor. Si la acción se tiene que ejecutar en una configuración de entorno específica, los contenedores de Docker son una buena manera de hacerlo porque permiten personalizar el sistema operativo y las herramientas. La desventaja es que, como el trabajo tiene que crear y recuperar el contenedor, las acciones de contenedor de Docker suelen ser más lentas que las acciones de JavaScript.

Antes de crear una acción de contenedor de Docker, debe tener conocimientos básicos sobre cómo usar las variables de entorno y el sistema de archivos de contenedor de Docker. Los pasos que debe seguir para crear una acción de contenedor de Docker son mínimos y sencillos:

1. Cree un elemento Dockerfile a fin de definir los comandos para ensamblar la imagen de Docker.
2. Cree un archivo de metadatos action.yml para definir las entradas y salidas de la acción. En el archivo, establezca el valor runs: using: en docker y el valor runs: image: en Dockerfile.
3. Cree un archivo entrypoint.sh para describir la imagen de Docker.
4. Confirme e inserte la acción en GitHub con los archivos siguientes: action.yml, entrypoint.sh, Dockerfile y README.md.

Acciones de JavaScript

Las acciones de JavaScript se pueden ejecutar directamente en la máquina del ejecutor y separan el código de acción del entorno que se usa para ejecutar la acción. Por este motivo, el código de acción se simplifica y se puede ejecutar más rápido que las acciones dentro de un contenedor de Docker.

Como requisito previo para crear y usar acciones de JavaScript empaquetadas, debe descargar Node.js, que incluye npm. Como paso opcional (pero recomendado), use el módulo GitHub Actions Toolkit de Node.js, que es una recopilación de paquetes de Node.js que le permite crear rápidamente acciones de JavaScript con más coherencia.

Los pasos que debe seguir para crear una acción de JavaScript son mínimos y sencillos:

1. Cree un archivo de metadatos action.yml para definir las entradas y salidas de la acción, así como para indicarle al ejecutor de acciones cómo empezar a ejecutar esta acción de JavaScript.
2. Cree un archivo index.js con información de contexto sobre los paquetes del kit de herramientas, el enrutamiento y otras funciones de la acción.
3. Confirme e inserte la acción en GitHub con los archivos siguientes: action.yml, index.js, node_modules, package.json, package-lock.json y README.md.

Acciones de pasos de ejecución compuestos

Las acciones de pasos de ejecución compuestos permiten reutilizar acciones mediante scripts de shell. Incluso puede combinar varios lenguajes de shell dentro de la misma acción. Si tiene muchos scripts de shell para automatizar varias tareas, ahora puede convertirlos fácilmente en una acción y reutilizarlos para diferentes flujos de trabajo. A veces es más fácil escribir un script de shell que usar JavaScript o encapsular el código en un contenedor de Docker.

Metadatos y sintaxis necesarios para crear una acción

Al crear o revisar una acción de GitHub, un primer paso excelente consiste en revisar el archivo action.yml para evaluar qué entradas, salidas, descripción, ejecuciones y otra información de configuración necesita la acción. Algunos de estos parámetros son necesarios, mientras que otros son opcionales. El archivo action.yml define la información siguiente sobre la acción:

Parámetro	Descripción	Obligatorio
Nombre	Nombre de la acción. Ayuda a identificar visualmente la acción en un trabajo.	sí
Descripción	Resumen de lo que hace la acción.	sí
Entradas	Los parámetros de entrada permiten especificar los datos que la acción espera usar durante el tiempo de ejecución. Estos parámetros se convierten en variables de entorno en el ejecutor.	no
Salidas	Los parámetros de salida permiten especificar datos que acciones posteriores pueden usar más adelante en el flujo de trabajo, después de que se haya ejecutado la acción que define estas salidas.	no
Ejecuciones	Comando que se ejecutará cuando se ejecute la acción.	sí
Personalización de marca	Icono de color y de pluma que se usará a fin de crear un distintivo para personalizar y distinguir la acción en Marketplace de GitHub.	no

Entradas

Las entradas son los parámetros que permiten especificar los datos que la acción espera usar en tiempo de ejecución. GitHub almacena estos parámetros de entrada como variables de entorno.

A continuación se muestra un ejemplo de una lista de entradas para una acción. La entrada firstNameStudent es opcional, mientras que studentGrade es obligatoria.

inputs:
  firstNameStudent:
    description: 'First name of student'
    required: false
    default: '1'
  studentGrade:
    description: 'Grade of the student'
    required: true

Salidas

Las salidas son los parámetros que permiten declarar datos. Tenga en cuenta que las acciones que se ejecutan posteriormente en un flujo de trabajo pueden usar los datos de salida que se hayan declarado en una acción ejecutada anteriormente.

El ejemplo siguiente es una salida sencilla para declarar la nota media de los alumnos:

outputs:
  average:
    description: 'The average grade of the students'

Ejecuciones

Como ha visto antes, la acción debe tener una instrucción runs que defina el comando necesario para ejecutar la acción. En función de cómo cree la acción, independientemente de si usa un contenedor de Docker, JavaScript o pasos de ejecución compuestos, la sintaxis de runs se define de manera diferente.

runs para acciones de Docker

Las acciones de contenedor de Docker necesitan que la instrucción runs configure la imagen que la acción de Docker usa con los argumentos siguientes:

• using: se debe establecer en docker para ejecutar una acción de contenedor de Docker.
• image: imagen de Docker que se usa como contenedor para ejecutar la acción.

runs:
  using: 'docker'
  image: 'Dockerfile'

runs para acciones de JavaScript

Las acciones de JavaScript necesitan que la instrucción runs tome los dos argumentos siguientes:

• using: aplicación utilizada para ejecutar el código tal y como se define en main.
• main: archivo que contiene el código de acción; la aplicación definida en using ejecuta este archivo.

Por ejemplo, esta es una instrucción runs para una acción de JavaScript mediante Node.js:

runs:
  using: 'node12'
  main: 'main.js'

runs para acciones de paso de ejecución compuesto

Las acciones de pasos de ejecución compuestos necesitan que la instrucción runs tome los tres argumentos siguientes:

• using: se debe establecer en "composite" para ejecutar un paso de ejecución compuesto.
• steps: pasos de ejecución para ejecutar la acción.
• steps[*].run: comando que se quiere ejecutar (puede estar en línea o un script en el repositorio de acciones).

Por ejemplo, esta es una instrucción runs para una acción de paso de ejecución compuesto que ejecutará el script en la ruta de archivos /test/script/sh:

runs:
  using: "composite"
  steps:
    - run: ${{ github.action_path }}/test/script.sh
      shell: bash

Personalización de marca

Una característica opcional pero divertida es la capacidad de personalizar el distintivo de la acción. El distintivo se muestra junto al nombre de la acción en Marketplace de GitHub. Puede usar un color y un icono de pluma para crear el distintivo. Para la personalización de marca, tendrá que especificar el icono y el color que quiera usar.

branding:
  icon: 'shield'  
  color: 'blue'

Este es un ejemplo de un distintivo para la acción de finalizar la compra en Marketplace de GitHub:

Comandos de flujo de trabajo

La creación de un flujo de trabajo es bastante sencilla siempre que pueda encontrar las acciones correctas para los pasos. En algunos casos, es posible que tenga que crear acciones propias para lograr los resultados deseados, pero puede usar comandos de flujo de trabajo para agregar otro nivel de personalización a los flujos de trabajo.

Los comandos de flujo de trabajo le permiten comunicarse con el ejecutor de Acciones de GitHub mediante la impresión de líneas de texto con formato en la consola. Puede usar estos comandos de flujo de trabajo con comandos de shell o dentro de las acciones personalizadas. Los comandos de flujo de trabajo son útiles porque permiten compartir información entre los pasos de flujo de trabajo, imprimir mensajes de depuración o error en la consola, establecer variables de entorno y parámetros de salida, o agregar a la ruta de acceso del sistema.

La mayoría de los comandos de flujo de trabajo usan el comando echo en el formato específico siguiente, mientras que otros se pueden invocar escribiendo en un archivo:

echo "::workflow-command parameter1={data},parameter2={data}::{command value}"

A continuación se muestran algunos ejemplos básicos de registro de mensajes para imprimir un mensaje de depuración, de información, de error o de advertencia en la consola:

- name: workflow commands logging messages
  run: |
    echo "::debug::This is a debug message"
    echo "This is an info message"
    echo "::error::This is an error message"
    echo "::warning::This is a warning message"

También puede crear un mensaje para imprimir en el registro con un nombre de archivo (file), un número de línea (line) y un número de columna (col) donde se ha producido el error. Los mensajes de advertencia aparecen en un resaltado amarillo con el texto "warning" (advertencia) y los mensajes de error en un resaltado rojo con el texto "error".

echo "::error file=app.js,line=10,col=15::Something went wrong"

Es importante tener en cuenta que estos comandos de flujo de trabajo deben estar en una sola línea. Los caracteres que interfieren con el análisis, como las comas y los saltos de línea, tendrán que estar codificados con dirección URL.

Por ejemplo, el texto siguiente es un mensaje de varias líneas:

This text spans
across multiple lines

Este mensaje debe codificarse como se muestra a continuación:

This text spans%0Aacross multiple lines

Además de los comandos de flujo de trabajo, puede definir códigos de salida para establecer el estado de una acción. Esto es importante porque cuando se trabaja con trabajos en un flujo de trabajo; un código de salida con error detendrá todas las acciones simultáneas y cancelará las acciones futuras. Si va a crear una acción de JavaScript, puede usar el paquete @actions/core del kit de herramientas de acciones para registrar un mensaje y establecer un código de salida de error. Si va a crear una acción de contenedor de Docker, puede establecer un código de salida de error en el script entrypoint.sh.