Acercad e las acciones personalizadas

Acercad e las acciones personalizadas

Puedes crear acciones por medio de a escritura de un código personalizado que interactúe con tu repositorio de la manera que desees, incluida la integración con las API de GitHub y cualquier API de terceros disponible públicamente. Por ejemplo, una acción puede publicar módulos npm, enviar alertas por SMS cuando se crean propuestas urgentes o implementar un código listo para producción.

Las acciones pueden ejecutarse directamente en una máquina o en un contenedor Docker. Puedes definir las entradas, salidas y variables de entorno de una acción.

Tipos de acciones

Puedes crear acciones de contenedor Docker y JavaScript. Las acciones requieren un archivo de metadatos para definir las entradas, salidas y puntos de entrada para tu acción. El nombre del archivo de metadatos debe ser action.yml o action.yaml. Para obtener más información, consulta "Sintaxis de metadatos para GitHub Actions"

Tipo	Sistema operativo
Contenedor Docker	Linux
JavaScript	Linux, macOS, Windows
Acciones compuestas	Linux, macOS, Windows

Acciones del contenedor Docker

Los contenedores Docker empaquetan el entorno con el código de las GitHub Actions. Esto crea una unidad de trabajo más consistente y confiable, ya que el consumidor de la acción no necesita preocuparse por las herramientas o las dependencias.

Un contenedor Docker te permite usar versiones específicas de un sistema operativo, dependencias, herramientas y código. Para las acciones que se deben ejecutar en una configuración de entorno específica, Docker es una opción ideal porque puedes personalizar el sistema operativo y las herramientas. Debido a la latencia para crear y recuperar el contenedor, las acciones del contenedor Docker son más lentas que las acciones de JavaScript.

Las acciones de contenedor de Docker solo pueden ejecutarse en ejecutores con un sistema operativo Linux. Los ejecutores auto-hospedados deberán utilizar un sistema operativo Linux y tener Docker instalado para ejecutar las acciones de contenedores de Docker. Para obtener más información acerca de los requisitos de los ejecutores auto-hospedados, consulta la sección "Acerca de los ejecutores auto-hospedados".

Acciones de JavaScript

Las acciones de JavaScript pueden ejecutarse directamente en una máquina del ejecutor y separar el código de acción del entorno utilizado para ejecutar el código. El uso de una acción de JavaScript simplifica el código de acción y se ejecuta más rápido que una acción de contenedor Docker.

Para garantizar que tus acciones de JavaScript son compatibles con todos los ejecutores hospedados en GitHub (Ubuntu, Windows, y macOS), el código empaquetado de JavaScript que escribas debe ser puramente JavaScript y no depender de otros binarios. Las acciones de JavaScript se ejecutan directamente en el ejecutor y utiliza binarios que ya existen en el ambiente virtual.

Si estás desarrollando un proyecto Node.js, el conjunto de herramientas de las GitHub Actions te ofrece paquetes que puedes usar en tu proyecto para acelerar el desarrollo. Para obtener más información, consulta el repositorio actions/toolkit.

Acciones compuestas

Una acción compuesta te permite combinar pasos de flujo de trabajo múltiples dentro de una acción. Por ejemplo, puedes utilizar esta característica para agrupar comandos de ejecución múltiples en una acción y luego tener un flujo de trabajo que ejecute estos comandos agrupados como un paso simple utilizando dicha acción. Para ver un ejemplo, revisa la sección "Crear una acción compuesta".

Elegir una ubicación para tu acción

Si estás desarrollando una acción para que otras personas la utilicen, te recomendamos mantener la acción en su propio repositorio en lugar de agruparla con otro código de aplicación. Esto te permite versionar, rastrear y lanzar la acción como cualquier otro software.

Puedes almacenar los archivos de dicha acción en cualquier ubicación de tu repositorio. Si tienes la intención de combinar la acción, el flujo de trabajo y el código de aplicación en un único repositorio, es recomendable que almacenes las acciones en el directorio .github. Por ejemplo, .github/actions/action-a y .github/actions/action-b.

Compatibilidad con GitHub Enterprise Server

Para garantizar de que tu acción es compatible con GitHub Enterprise Server, debes asegurarte de que no utilices ninguna referencia escrita a mano para las URL de la API de GitHub Enterprise Server. En vez de esto, deberías utilizar variables de ambiente para referirte a la API de GitHub Enterprise Server:

• Crear y validar un lanzamiento en una rama de lanzamiento (tal como release/v1) antes de crear la etiqueta de lanzamiento (por ejemplo, v1.0.2).
• Para el caso de GraphQL, utiliza la variable de ambiente GITHUB_GRAPHQL_URL.

Para obtener más información, consulta la sección "Variables de ambiente predeterminadas."

Utilizar la administración de lanzamientos para las acciones

Esta sección explica cómo puedes utilizar la administración de lanzamientos para distribuir actualizaciones a tus acciones de forma predecible.

Buenas prácticas para la administración de lanzamientos

Si estás desarrollando una acción para que la utilicen otras personas, te recomendamos utilizar la administración de lanzamientos para controlar cómo distribuyes las actualizaciones. Los usuarios pueden esperar que una versión mayor de una acción incluya correcciones críticas y parches de seguridad necesarios y que se mantenga compatible con los flujos de trabajo existentes. Deberías considerar lanzar una versión mayor cada que tus cambios afecten la compatibilidad.

Bajo este acercamiento de administración de lanzamientos, los usuarios no deberían referenciar una rama predeterminada de una acción, ya que es probable que contenga el código más reciente y, en consecuencia, podría ser inestable. En vez de esto, puedes recomendar a tus usuarios que especifiquen una versión mayor cuando utilicen tu acción, y únicamente dirigirlos a una versión más específica si encuentran algún problema.

Para utilizar una versión específica de la acción, los usuarios pueden configurar su flujo de trabajo de GitHub Actions para apuntar a una etiqueta, el SHA de una confirmación o a una rama denominada para un lanzamiento.

Utilizar etiquetas para la administración de lanzamientos

Te recomendamos utilizar etiquetas para la administración de lanzamientos de acciones. Al utilizar este acercamiento, tus usuarios pueden distinguir claramente entre las versiones mayores y menores:

• Crear y validar un lanzamiento en una rama de lanzamiento (tal como release/v1) antes de crear la etiqueta de lanzamiento (por ejemplo, v1.0.2).
• Crear un lanzamiento utilizando un versionamiento semántico. Para obtener más información, consulta "Creating releases (Crear lanzamientos)".
• Mover la etiqueta de versión mayor (tal como v1, v2) para apuntar a la referencia de Git en el lanzamiento actual. Para obtener más información, consulta Conceptos básicos de Git: etiquetas".
• Introducir una etiqueta de versión mayor (v2) para los cambios que modificarán sustancialmente los flujos de trabajo existentes. Por ejemplo, un cambio importante será cambiar las entradas de una acción.
• Las versiones mayores pueden lanzarse inicialmente con una etiqueta de beta para indicar su estado, por ejemplo, v2-beta. La etiqueta -beta puede eliminarse entonces cuando esté listo.

Este ejemplo ilustra como un usuario puede referenciar una etiqueta de un lanzamiento mayor:

steps:
    - uses: actions/javascript-action@v1

Este ejemplo ilustra como un usuario puede referenciar una etiqueta de lanzamiento de un parche específico:

steps:
    - uses: actions/javascript-action@v1.0.1

Utilizar ramas para la administración de lanzamientos

Si prefieres utilizar nombres de rama para la administración de lanzamientos, este ejemplo demuestra como referenciar una rama nombrada:

steps:
    - uses: actions/javascript-action@v1-beta

Utilizar el SHA de las confirmaciones para la administración de lanzamientos

Cada confirmación de Git recibe un valor calculado de SHA, el cual es único e inmutable. Los usuarios de tus acciones podrían preferir obtener un valor de SHA para la confirmación, ya que este acercamiento puede ser más confiable que especificar una etiqueta, la cual podría borrarse o moverse. Sin embargo, esto significa que los usuarios no recibirán ls actualizaciones posteriores que se hagan a la acción. El utilizar el valor completo del SHA de la confirmación en vez del abreviado ayuda a prevenir que las personas utilicen una confirmación mal intencionada que utiice la misma abreviación.

steps:
    - uses: actions/javascript-action@172239021f7ba04fe7327647b213799853a9eb89

Crear un archivo README para tu acción

Si tienes la intención de compartir públicamente tu acción, te recomendamos crear un archivo README para ayudar a las personas a que aprendan a usar tu acción. Puedes incluir esta información en tu README.md:

• Una descripción detallada de lo que hace la acción.
• Argumentos necesarios de entrada y salida.
• Argumentos opcionales de entrada y salida.
• Secretos que utiliza la acción.
• Variables de entorno que utiliza la acción.
• Un ejemplo de cómo usar tu acción en un flujo de trabajo.

Comparar GitHub Actions para GitHub Apps

GitHub Marketplace ofrece herramientas para mejorar tu flujo de trabajo. Comprender las diferencias y los beneficios de cada herramienta te permitirá seleccionar la mejor herramienta para tu trabajo. Para obtener más información acerca de la creación de apps, consulta "Acerca de las apps".

Fortalezas de las acciones y las aplicaciones de GitHub

Si bien tanto las GitHub Actions como las GitHub Apps proporcionan formas de crear herramientas de flujo de trabajo y automatización, pueden tener fortalezas que las hagan útiles en formas diferentes.

GitHub Apps:

• Se ejecutan de manera persistente y pueden reaccionar rápidamente a los eventos.
• Funcionan bien cuando se necesitan datos de manera persistente.
• Funcionan mejor con las solicitudes de API que no consumen mucho tiempo.
• Se ejecutan en un servidor o infraestructura de computación que proporciones.

GitHub Actions:

• Brindan automatización que puede realizar una integración continua y una implementación continua.
• Pueden ejecutarse directamente en máquinas de ejecutor o en contenedores Docker.
• Pueden incluir acceso a un clon de tu repositorio, lo que permite que las herramientas de implementación y publicación, los formateadores de código y las herramientas de la línea de comando accedan a tu código.
• No necesitan que implementas un código o que sirvas una aplicación.
• Tienen una interfaz simple para crear y usar secretos, que permite que las acciones interactúen con servicios de terceros sin la necesidad de almacenar las credenciales de la persona que utiliza la acción.

Leer más

• "Herramientas de desarrollo para GitHub Actions"