Administración de acciones personalizadas

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.

El almacenamiento de una acción en su propio repositorio facilita a la GitHub comunidad detectar la acción, limita el ámbito de la base de código para los desarrolladores que corrigen problemas y amplían la acción y desacoplan el control de versiones de la acción del control de versiones de otro código de aplicación.

Si va a crear una acción que no planea poner a disposición de otros usuarios, puede almacenar los archivos de la acción en cualquier ubicación del 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

Muchas personas acceden GitHub a 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 Referencia de 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

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 usar una versión de acción específica, los usuarios pueden configurar su GitHub Actions flujo de trabajo para que tenga como destino una etiqueta, el SHA de una confirmación o una rama denominada para una versión.

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:

1. Desarrollar y validar una versión en una rama de versión (por ejemplo, release/v1).
2. Crea una versión con una etiqueta de versión mediante el versionado semántico (por ejemplo, v1.0.1). Para más información, consulta Administrar lanzamientos en un repositorio.
3. Mueve la etiqueta de versión principal (como v1) para que apunte a la referencia de Git de la versión actual. Para obtener más información, consulta Conceptos básicos de Git: etiquetado.
4. Introduce una nueva etiqueta de versión principal (por ejemplo, v2) para los cambios que interrumpirán los flujos de trabajo existentes, como cambiar las entradas de una acción.

Sintaxis para hacer referencia a etiquetas

Este ejemplo ilustra como un usuario puede referenciar una etiqueta de una versión principal:

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 gestión de versiones

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 tu acción podrían preferir basarse en el valor SHA de un commit, ya que este enfoque puede ser más confiable que especificar una etiqueta, la cual podría eliminarse o desplazarse. 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 emplea 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.