Publicación de una acción de GitHub personalizada

Completado

Aquí, obtendrá información sobre cómo elegir la visibilidad adecuada para la acción, los procedimientos recomendados para documentar y crear versiones de la acción, y cómo publicarla en Marketplace de GitHub.

Elección de una ubicación para la acción

Al crear una acción, es importante decidir en primer lugar dónde se quiere crear y su visibilidad, ya sea public o private. La visibilidad de la acción determina qué recomendaciones y requisitos son necesarios para publicarla. Ahora se examinarán con más detalle estas dos opciones de visibilidad.

Público

Los flujos de trabajo de cualquier repositorio pueden usar acciones públicas. Si va a desarrollar una acción con la intención de que sea de código abierto o de que esté disponible públicamente por medio de Marketplace de GitHub, una recomendación y, en la mayoría de los casos, un requisito, es que la acción tenga su propio repositorio en lugar de agruparla con otro código de aplicación. Esto le permite crear versiones de la acción, realizar su seguimiento y publicarla como cualquier otro fragmento de software. Esto facilita que la comunidad de GitHub descubra la acción, limite el ámbito de la base de código para los desarrolladores que corrigen problemas y extienden la acción, y separa el control de versiones de la acción del de otro código de la aplicación.

Private

Cuando una acción está en un repositorio privado, solo los flujos de trabajo del mismo repositorio pueden usarla. Con las acciones privadas, puede almacenar los archivos de la acción en cualquier ubicación del repositorio. Si tiene previsto combinar código de acción, flujo de trabajo y aplicación en un único repositorio, se recomienda almacenar la acción en el directorio .github. Por ejemplo, .github/actions/action-a y .github/actions/action-b.

Documentación de la acción

Puede resultar muy frustrante usar una nueva herramienta o aplicación cuando la documentación es imprecisa o incluso falta. Es importante incluir una buena documentación con la acción para que otros usuarios puedan ver cómo funciona, ya sea que pretenda hacerla pública o privada. Lo primero que hay que hacer es crear un buen archivo README.md para la acción.

El archivo README.md suele ser lo primero que consultan los desarrolladores para ver cómo funciona la acción. Es un excelente lugar para incluir toda la información importante para la acción. A continuación se muestra una lista no exhaustiva de los elementos que se deben incluir:

• 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.

Como regla general, el archivo README.md debe incluir todo lo que un usuario debe saber para usar la acción. Si cree que podría ser información útil, inclúyala en README.md.

Publicación y versión de la acción

Si va a desarrollar una acción para que la utilicen otros usuarios, ya sea pública o privada, debe definir una estrategia de administración de versiones para controlar cómo se distribuyen las actualizaciones. Las actualizaciones de versiones principales, incluidas las correcciones críticas necesarias y las revisiones de seguridad que afectan a la compatibilidad, se deben documentar con claridad.

Procedimientos recomendados para la administración de versiones

Una buena estrategia de administración de versiones debe incluir recomendaciones de control de versiones. Los usuarios no deben hacer referencia a la rama predeterminada de una acción con la acción, porque es probable que dicha rama contenga el código más reciente (que podría ser estable o no), lo que podría interrumpir el flujo de trabajo. En su lugar, se recomienda que los usuarios especifiquen una versión principal al utilizar la acción y solo dirigirlos a una versión más específica si encuentran problemas. Pueden hacerlo mediante la configuración del flujo de trabajo de Acciones de GitHub para que tenga como destino una etiqueta, el valor SHA de una confirmación o una rama específica con nombre para una versión. Ahora se examinarán estas opciones con más detalle.

Etiquetas

Las etiquetas pueden ser una buena manera de administrar las versiones de una acción. Con las etiquetas, los usuarios pueden distinguir fácilmente entre versiones principales y secundarias. A continuación se muestra una lista de procedimientos útiles que se deben tener en cuenta al crear versiones:

• 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).
• Use el control de versiones semántico.
• Mueva la etiqueta de versión principal (como v1, v2) para que apunte a la referencia de Git de la versión actual.
• Introduzca una nueva etiqueta de versión principal (v2) para los cambios que interrumpirán los flujos de trabajo existentes.
• Publique las versiones principales con una etiqueta beta para indicar su estado, por ejemplo, v2-beta. Puede quitar la etiqueta -beta cuando la versión esté lista.

A continuación se muestran algunos ejemplos de cada opción.

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

Uso del valor SHA de una confirmación

Las etiquetas son útiles y se utilizan con frecuencia, pero una desventaja de su uso es que se pueden eliminar o mover. Con Git, cada confirmación recibe un valor SHA calculado, que es único y no se puede modificar. El uso de un valor SHA de confirmación para el control de versiones constituye la manera más confiable y segura de crear versiones y usar una acción. Pero a menudo en Git puede abreviar el hash SHA a los primeros caracteres y Git reconocerá la referencia. Si usa el valor SHA de la confirmación para la administración de versiones, debe usar el valor completo y no el abreviado.

steps:
    - uses: actions/javascript-action@2522385f6f7ba04fe7327647b213799853a8f55c

Publicación de una acción en Marketplace de GitHub

Cuando esté listo para compartir la acción con la comunidad de GitHub, puede publicarla en Marketplace de GitHub y comunicarse con millones de usuarios de GitHub. Las acciones publicadas en Marketplace de GitHub se publican inmediatamente si se cumplen todos los requisitos. GitHub debe revisar las acciones que no cumplan los requisitos antes de publicarse. Tendrá que asegurarse de que el repositorio solo incluye el archivo de metadatos, el código y los archivos necesarios para la acción. Crear un repositorio único para la acción te permite etiquetar, lanzar y empaquetar el código en una sola unidad. GitHub también usa los metadatos de la acción en la página de Marketplace de GitHub.

A continuación se muestran los requisitos para publicar una acción en Marketplace de GitHub. Se aplican tanto a acciones basadas en contenedores de Docker como a acciones basadas en JavaScript:

• La acción debe estar en un repositorio público.
• Cada repositorio debe contener una sola acción.
• El archivo de metadatos de la acción (action.yml o action.yaml) debe estar en el directorio raíz del repositorio.
• En el archivo de metadatos de la acción, name debe ser único en Marketplace de GitHub.
  • El nombre no puede coincidir con un usuario u organización en GitHub, a menos que el usuario o el propietario de la organización publique la acción. Por ejemplo, solo la organización de GitHub puede publicar una acción denominada github.
  • name no puede coincidir con una categoría existente en Marketplace de GitHub.
  • name no puede coincidir con una característica existente de GitHub.

Puede agregar la acción que ha creado a Marketplace de GitHub si la etiqueta como una nueva versión y después la publica. Hay algunos pasos guiados en GitHub que le permiten publicar una versión de la acción. Puede encontrar más información sobre estos pasos en la sección de resumen al final de este módulo.