Sintaxis de metadatos para acciones de GitHub

Acerca de la nueva sintaxis YAML para GitHub Actions

Las acciones Docker y JavaScript requieren un archivo de metadatos. El nombre del archivo de metadatos debe ser action.yml o action.yaml. Los datos del archivo de metadatos definen las entradas, las salidas y el punto de entrada principal para tu acción.

Los archivos de metadatos de acción usan la sintaxis YAML. Si eres nuevo en YAML, puedes leer "Aprender YAML en cinco minutos".

name (nombre)

Requerido El nombre de tu acción. GitHub muestra el name (nombre) en la pestaña Actions (Acciones) para ayudarte a identificar visualmente las acciones en cada trabajo.

autor

Opcional El nombre del autor de las acciones.

descripción

Requerido Una descripción breve de la acción.

inputs (entrada)

Opcional Los parámetros de entrada te permiten especificar datos que la acción espera para usar durante el tiempo de ejecución. GitHub almacena parámetros de entrada como variables de entorno. Las Id de entrada con letras mayúsculas se convierten a minúsculas durante el tiempo de ejecución. Recomendamos usar Id de entrada en minúsculas.

Ejemplo

Este ejemplo configura dos entradas: numOctocats y octocatEyeColor. La entrada numOctocats no se requiere y se predeterminará a un valor de '1'. Se requiere la entrada octocatEyeColor y no tiene un valor predeterminado. Los archivos de flujo de trabajo que usan esta acción deben usar la palabra clave with (con) para establecer un valor de entrada para octocatEyeColor. Para obtener información sobre la sintaxis with (con), consulta "Sintaxis de flujo de trabajo para GitHub Actions".

inputs:
  numOctocats:
    description: 'Number of Octocats'
    required: false
    default: '1'
  octocatEyeColor:
    description: 'Eye color of the Octocats'
    required: true

Cuando especificas una entrada en un archivo de flujo de trabajo o usas un valor de entrada predeterminado, GitHub crea una variable de entorno para la entrada con el nombre INPUT_<VARIABLE_NAME>. La variable de entorno creada convierte los nombre de entrada en letras mayúscula y reemplaza los espacios con los caracteres _.

Si la acción se escribió utilizando pasos de ejecución compuestos, entonces no obtendrá automáticamente una INPUT_<VARIABLE_NAME>. Si la conversión no ocurre, puedes cambiar estas entradas manualmente.

Para acceder a la variable de ambiente en una acción de contenedor de Docker, debes pasar la entrada utilizando la palabra clave args en el archivo de metadatos de la acción. Para obtener más información sobre el archivo de metadatos de la acción para las acciones de contenedor de Docker, consulta la sección "Crear una acción de contenedor de Docker".

Por ejemplo, si un flujo de trabajo definió las entradas de numOctocats y octocatEyeColor, el código de acción pudo leer los valores de las entradas utilizando las variables de ambiente INPUT_NUMOCTOCATS y INPUT_OCTOCATEYECOLOR.

inputs.<input_id>

Requerido Un identificador string (cadena) para asociar con la entrada. El valor de <input_id> es un mapa con los metadatos de la entrada. <input_id> debe ser un identificador único dentro del objeto inputs (entradas). El <input_id>> debe comenzar con una letra o _ y debe contener solo caracteres alfanuméricos, -, o _.

inputs.<input_id>.description

Requerido Una descripción de string del parámetro de entrada.

inputs.<input_id>.required

Requerido Un boolean (booleano) para indicar si la acción requiere el parámetro de entrada. Establecer en true cuando se requiera el parámetro.

inputs.<input_id>.default

Opcional Una string que representa el valor predeterminado. El valor predeterminado se usa cuando un parámetro de entrada no se especifica en un archivo de flujo de trabajo.

inputs.<input_id>.deprecationMessage

Opcional Si se utiliza el parámetro de entrada, esta string se registrará como un mensaje de advertencia. Puedes utilizar esta advertencia para notificar a los usuarios que la entrada es obsoleta y mencionar cualquier alternativa.

outputs (salidas)

Opcional Los parámetros de salida te permiten declarar datos que una acción establece. Las acciones que se ejecutan más tarde en un flujo de trabajo pueden usar el conjunto de datos de salida en acciones de ejecución anterior. Por ejemplo, si tuviste una acción que realizó la adición de dos entradas (x + y = z), la acción podría dar como resultado la suma (z) para que otras acciones la usen como entrada.

Si no declaras una salida en tu archivo de metadatos de acción, todavía puedes configurar las salidas y utilizarlas en un flujo de trabajo. Para obtener más información acerca de la configuración de salidas en una acción, consulta "Comandos de flujo de trabajo para GitHub Actions".

Ejemplo

outputs:
  sum: # id of the output
    description: 'The sum of the inputs'

outputs.<output_id>

Requerido Un identificador string para asociar con la salida. El valor de <output_id> es un mapa con los metadatos de la salida. <output_id> debe ser un identificador único dentro del objeto outputs (salidas). El <output_id>> debe comenzar con una letra o _ y debe contener solo caracteres alfanuméricos, -, o _.

outputs.<output_id>.description

Requerido Una descripción de string del parámetro de salida.

outputs para las acciones compuestas

Los outputs Opcionales utilizan los mismos parámetros que los outputs.<output_id> and los outputs.<output_id>.description (consulta la sección "outputs para GitHub Actions"), pero también incluyen el token de value.

Ejemplo

outputs:
  random-number:
    description: "Random number"
    value: ${{ steps.random-number-generator.outputs.random-id }}
runs:
  using: "composite"
  steps:
    - id: random-number-generator
      run: echo "::set-output name=random-id::$(echo $RANDOM)"
      shell: bash

outputs.<output_id>.value

Requerido El valor al cual se mapeará el parámetro de salida. Puedes configurarlo a una string o a una expresión con contexto. Por ejemplo, puedes utilizar el contexto steps para configurar el value de una salida al valor de salida de un paso.

Para obtener más información sobre cómo utilizar la sintaxis de contexto, consulta la sección de "Contextos"

runs para acciones de JavaScript

Requerido Configura la ruta al código de la acción y a la aplicación que se utiliza para ejecutar dicho código.

Ejemplo usando Node.js

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

runs.using

Requerido La aplicación utilizada para el código especificado en main.

runs.main

Requerido El archivo que contiene tu código de acción. La aplicación especificada en using ejecuta este archivo.

pre

Opcional Te permite ejecutar un script al inicio de un job, antes de que la acción main: comience. Por ejemplo, puedes utilizar pre: para ejecutar un script de configuración de pre-requisitos. La aplicación que se especifica con la sintaxis using ejecutará este archivo. La acción pre: siempre se ejecuta predeterminadamente pero puedes invalidarla utilizando pre-if.

En este ejemplo, la acción pre: ejecuta un script llamado setup.js:

runs:
  using: 'node12'
  pre: 'setup.js'
  main: 'index.js'
  post: 'cleanup.js'

pre-if

Opcional Te permite definir las condiciones para la ejecución de la acción pre:. La acción pre: únicamente se ejecutará si se cumplen las condiciones en pre-if. Si no se configura, pre-if se configurará predefinidamente como always(). Nota que el contexto step no está disponible, ya que no se ha ejecutado ningún paso todavía.

En este ejemplo, cleanup.js se ejecuta únicamente en los ejecutores basados en linux:

  pre: 'cleanup.js'
  pre-if: runner.os == 'linux'

publicación

Opcional Te permite ejecutar un script al final de un job, una vez que se haya completado la acción main:. Por ejemplo, puedes utilizar post: para finalizar algunos procesos o eliminar los archivos innecesarios. La aplicación que se especifica con la sintaxis using ejecutará este archivo.

En este ejemplo, la acción post: ejecuta un script llamado cleanup.js:

runs:
  using: 'node12'
  main: 'index.js'
  post: 'cleanup.js'

La acción post: siempre se ejecuta predeterminadamente, pero la puedes invalidar utilizando post-if.

post-if

Opcional Te permite definir condiciones para la ejecución de la acción post:. La acción post únicamente se ejecutará si se cumplen las condiciones en post-if. Si no se configura, pre-if se configurará predeterminadamente como always().

Por ejemplo, este cleanup.js únicamente se ejecutará en ejecutores basados en Linux:

  post: 'cleanup.js'
  post-if: runner.os == 'linux'

runs para las acciones compuestas

Requerido Configura la ruta a la acción compuesta, y la aplicación que se utiliza para ejecutar el código.

runs.using

Requerido Para utilizar una acción compuesta, configúralo como "composite".

runs.steps

Requerido Los pasos que planeas ejecutar en esta acción.

runs.steps[*].run

Requerido El comando que quieres ejecutar. Este puede estar dentro de la línea o ser un script en tu repositorio de la acción:

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

Como alternativa, puedes utilizar $GITHUB_ACTION_PATH:

runs:
  using: "composite"
  steps:
    - run: $GITHUB_ACTION_PATH/script.sh
      shell: bash

Para obtener más información, consulta la sección "``".

runs.steps[*].shell

Requerido El shell en donde quieres ejecutar el comando. Puedes utilizar cualquiera de los shells listados aquí. Requerido si se configuró run.

runs.steps[*].name

Opcional El nombre del paso compuesto.

runs.steps[*].id

Opcional Un identificador único para el paso. Puede usar el id para hacer referencia al paso en contextos. Para obtener más información, consulta "Contextos".

runs.steps[*].env

Opcional Configura un map de variables de ambiente únicamente para este paso. Si quieres modificar las variables de ambiente que se almacenan en el flujo de trabajo, utiliza echo "::set-env name={name}::{value}" en un paso compuesto.

runs.steps[*].working-directory

Opcional Especifica el directorio de trabajo en donde se ejecuta un comando.

runs para acciones de Docker

Requerido Configura la imagen utilizada para la acción de Docker.

Ejemplo utilizando un Dockerfile en tu repositorio

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

Ejemplo usando un contenedor de registro Docker público

runs:
  using: 'docker'
  image: 'docker://debian:stretch-slim'

runs.using

Requerido Debes configurar este valor como 'docker'.

pre-entrypoint

Opcional Te permite ejecutar un script antes de que comience la acción entrypoint. Por ejemplo, puedes utilizar pre-entrypoint para ejecutar un script de configuración de pre-requisitos. GitHub Actions utiliza docker run para lanzar esta acción, y ejecuta el script dentro de un contenedor nuevo que utiliza la misma imagen base. Esto significa que el estado del tiempo de ejecución difiere de el contenedor principal entrypoint, y se deberá acceder a cualquier estado que requieras ya sea en el espacio de trabajo, HOME, o como una variable STATE_. La acción pre-entrypoint: siempre se ejecuta predeterminadamente pero la puedes invalidar utilizando pre-if.

La aplicación que se especifica con la sintaxis using ejecutará este archivo.

En este ejemplo, la acción pre.entrypoint: ejecuta un script llamado setup.sh:

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - 'bzz'
  pre-entrypoint: 'setup.sh'
  entrypoint: 'main.sh'

runs.image

Requerido La imagen de Docker a utilizar como el contenedor para ejecutar la acción. El valor puede ser el nombre de la imagen base de Docker, un Dockerfile local en tu repositorio, o una imagen pública en Docker Hub u otro registro. Para referenciar un Dockerfile local de tu repositorio, el archivo debe nombrarse como Dockerfile y debes utilizar una ruta relativa a tu archivo de metadatos de acción. La aplicación docker ejecutará este archivo.

runs.env

Opcional Especifica mapa clave/de valores de las variables del ambiente para configurar en el ambiente del contenedor.

runs.entrypoint

Opcional Invalida el ENTRYPOINT de Docker en el Dockerfile, o lo configura si no se había especificado anteriormente. Utiliza entrypoint cuando el Dockerfile no especifique un ENTRYPOINT o cuando quieras invalidar la instrucción de ENTRYPOINT. Si omites el entrypoint, se ejecutarán los comandos que especifiques en la instrucción ENTRYPOINT de Docker. La instrucción ENTRYPOINT de Docker tiene una forma de shell y una de exec. La documentación de ENTRYPOINT de Docker recomienda utilizar la forma de exec de la instrucción ENTRYPOINT.

Para obtener más información acerca de cómo se ejecuta el entrypoint, consulta la sección "Soporte de Dockerfile para GitHub Actions".

post-entrypoint

Opcional Te permite ejecutar un script de limpieza una vez que se haya completado la acción de runs.entrypoint. GitHub Actions utiliza docker run para lanzar esta acción. Ya que GitHub Actions ejecuta el script dentro de un contenedor nuevo utilizando la misma imagen base, el estado de tiempo de ejecución es diferente del contenedor principal de entrypoint. Puedes acceder a cualquier estado que necesites, ya sea en el espacio de trabajo, HOME, o como una variable STATE_. La acción post-entrypoint: siempre se ejecuta predeterminadamente, pero puedes invalidarla utilizando post-if.

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - 'bzz'
  entrypoint: 'main.sh'
  post-entrypoint: 'cleanup.sh'

runs.args

Opcional Una matriz de secuencias que defina las entradas para un contenedor de Docker. Las entradas pueden incluir cadenas codificadas de forma rígida. GitHub comunica los args en el ENTRYPOINT del contenedor cuando se inicia el contenedor.

Los args se usan en el lugar de la instrucción CMD en un Dockerfile. Si usas CMD en tu Dockerfile, usa los lineamientos ordenados por preferencia:

1. Los documentos requerían argumentos en el README de las acciones y las omiten desde la instrucción CMD.
2. Usa los valores predeterminados que permiten usar la acción sin especificar ningún args.
3. Si la acción expone una marca de --help, o algo similar, utilízala para hacer tu propia documentación de la acción.

Si necesitas pasar variables de ambiente a una acción, asegúrate que ésta ejecute un shell de comandos para realizar la sustitución de variables. Por ejemplo, si se configura tu atributo entrypoint como "sh -c", entoces args se ejecutará en un shell de comandos. Como alternativa, si tu Dockerfile utiliza un ENTRYPOINT para ejecutar el mismo comando ("sh -c"), entonces args se ejecutará en un shell de comandos.

Para obtener más información sobre el uso de la instrucción CMD con GitHub Actions, consulta la sección "Soporte de Dockerfile para GitHub Actions".

Ejemplo

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - ${{ inputs.greeting }}
    - 'foo'
    - 'bar'

branding (marca)

Puedes usar un color y un icono de Pluma para crear una insignia que personalice y diferencie tu acción. Los distintivos se muestran junto al nombre de tu acción en GitHub Marketplace.

Ejemplo

branding:
  icon: 'award'  
  color: 'green'

branding.color

El color de fondo de la insignia. Puede ser: blanco, amarillow, azul, verde, anaranjado, rojo, púrpura o gris oscuro.

branding.icon

El nombre del icono de Pluma que se debe usar.