Acercad e las acciones personalizadas

Acercad e las acciones personalizadas

Puedes crear acciones escribiendo 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 problemas urgentes o implementar 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 un contenedor Docker, JavaScript y acciones compuestas. 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, vea «Sintaxis de metadatos para Acciones de GitHub».

Acciones de contenedor de Docker

Los contenedores Docker empaquetan el entorno con el código 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 ya que 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 más información sobre los requisitos de los ejecutores autohospedados, consulta "Acerca de los ejecutores autohospedados".

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 la 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 la imagen del ejecutor.

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, consulte el repositorio actions/toolkit.

Acciones compuestas

Una acción compuesta le permite combinar varios pasos de flujo de trabajo 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, consulta "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.

Para compartir las acciones en toda la empresa sin publicarlas de forma pública, puedes almacenarlas en un repositorio interno y luego configurarlo para que acceda a los flujos de trabajo de GitHub Actions en otros repositorios que sean propiedad de la misma organización o de una organización de la empresa. Para obtener más información, vea «Compartir acciones y flujos de trabajo con tu empresa».

Puedes almacenar los archivos de dicha acción en cualquier ubicación de tu repositorio. Si tiene previsto combinar un código de acción, de flujo de trabajo y de aplicación en un único repositorio, se recomienda almacenar las acciones en el directorio .github. Por ejemplo, .github/actions/action-a y .github/actions/action-b.

Compatibilidad con otras plataformas

Muchos usuarios acceden a GitHub en un dominio distinto de GitHub.com, como GHE.com o un dominio personalizado para GitHub Enterprise Server.

Para asegurarte de que la acción sea compatible con otras plataformas, no uses ninguna referencia codificada de forma rígida a direcciones URL de API como https://api.github.com. En su lugar, puedes:

• Usar variables de entorno (consulta "Almacenamiento de información en variables"):

  • Para la API de REST, use la variable de entorno GITHUB_API_URL.
  • Para GraphQL, use la variable de entorno GITHUB_GRAPHQL_URL.

• Usar un kit de herramientas como @actions/github, que puede establecer automáticamente las direcciones URL correctas.

Uso de la administración de versiones para 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 la versión del parche 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:

• Cree y valide una versión en una rama de versión (como release/v1) antes de crear la etiqueta de versión (por ejemplo, v1.0.2).
• Crear un lanzamiento utilizando un versionamiento semántico. Para obtener más información, vea «Administrar lanzamientos en un repositorio».
• Mueva la etiqueta de versión principal (como v1, v2) para que apunte a la referencia de Git de la versión actual. Para obtener más información, consulte "Conceptos básicos de Git: etiquetado".
• Introduzca una nueva etiqueta de versión principal (v2) para los cambios que interrumpirán los flujos de trabajo existentes. Por ejemplo, un cambio importante será cambiar las entradas de una acción.
• Las versiones principales se pueden publicar inicialmente con una etiqueta beta para indicar su estado, por ejemplo, v2-beta. La etiqueta -beta se puede quitar cuando la versión esté lista.

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. Debes utilizar un valor SHA completo de la confirmación y no un valor abreviado.

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

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. Puede incluir esta información en README.md:

• Una descripción detallada de lo que hace la acción.
• Argumentos obligatorios 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 sobre la creación de aplicaciones, consulta "Acerca de la creación de GitHub 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.

Información adicional

• "Comandos de flujo de trabajo para Acciones de GitHub"