Nota: Los ejecutores hospedados en GitHub no son compatibles con GitHub Enterprise Server actualmente. Puedes encontrar más información sobre el soporte que se tiene planeado en el futuro en el Itinerario público de GitHub.
Acerca de la nueva sintaxis YAML para GitHub Actions
Todas las acciones requieren un archivo de metadatos. El nombre del archivo de metadatos debe ser action.yml o action.yaml. Los datos en el archivo de metadatos definen las configuraciones de entradas, salidas y ejecuciones de 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: Especificar las entradas
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 para las acciones de contenedores de Docker y JavaScript
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.
Outputs are Unicode strings, and can be a maximum of 1 MB. The total of all outputs in a workflow run can be a maximum of 50 MB.
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: Declarar las salidas para las acciones de contenedores de Docker y JavaScript
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
Las outputs opcionales utilizan los mismos parámetros que outputs.<output_id> y outputs.<output_id>.description (consulta la sección de "outputs para acciones de contenedores de Docker y JavaScript"), pero también incluye el token value.
Outputs are Unicode strings, and can be a maximum of 1 MB. The total of all outputs in a workflow run can be a maximum of 50 MB.
Ejemplo: Declarar las salidas para las acciones compuestas
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
Requerido Especifica si es una acción de JavaScript, una acción compuesta o una acción de contenedor de Docker y cómo se ejecuta esta.
runs para acciones de JavaScript
Requerido Configura la ruta al código de la acción y el tiempo de ejecución que se utiliza para ejecutarlo.
Ejemplo: Utilizar Node.js v12
runs:
using: 'node12'
main: 'main.js'
runs.using
Requerido El tiempo de ejecución para ejecutar el código especificado en main.
- Utiliza
node12para Node.js v12.
runs.main
Requerido El archivo que contiene tu código de acción. El tiempo de ejecución que se especifica en using ejecuta este archivo.
runs.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. El tiempo de ejecución que ese especifica con la sintaxis de using ejecutará este archivo. La acción pre siempre se ejecuta predeterminadamente, pero puedes invalidar esto utilizando runs.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'
runs.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(). En pre-if, las funciones de verificación de estado evalúan contra el estado del job y no contra el estado de la propia acción.
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'
runs.post
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. El tiempo de ejecución que ese especifica con la sintaxis de 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.
runs.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(). En post-if, las funciones de verificación de estado evalúan contra el estado del job y no contra el estado de la propia acción.
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.
runs.using
Requerido Debes configurar este valor en '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 la variable de ambiente almacenada en el flujo de trabajo, utiliza echo "{name}={value}" >> $GITHUB_ENV en un paso compuesto.
runs.steps[*].working-directory
Opcional Especifica el directorio de trabajo en donde se ejecuta un comando.
runs.steps[*].continue-on-error
Opcional Impide que la acción falle cuando falla un paso. Se configura en true para permitir que la acción pase cuando falla este paso.
runs para las acciones de contenedores de Docker
Requerido Configura la imagen que se utiliza para la acción de contenedores de Docker.
Ejemplo: Utilizar un Dockerfile en tu repositorio
runs:
using: 'docker'
image: 'Dockerfile'
Ejemplo: Utilizar un contenedor de registro público de Docker
runs:
using: 'docker'
image: 'docker://debian:stretch-slim'
runs.using
Requerido Debes configurar este valor como 'docker'.
runs.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 puedes anular esto utilizando runs.pre-if.
El tiempo de ejecución que ese especifica con la sintaxis de 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 anular esto utilizando runs.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:
- Los documentos requerían argumentos en el README de las acciones y las omiten desde la instrucción
CMD. - Usa los valores predeterminados que permiten usar la acción sin especificar ningún
args. - 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", entonces 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: Definir argumentos para el contenedor de Docker
runs:
using: 'docker'
image: 'Dockerfile'
args:
- ${{ inputs.greeting }}
- 'foo'
- 'bar'
branding
Puedes usar un color y un icono de Feather 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: Configurar la personalización de una acción
branding:
icon: 'award'
color: 'green'
branding.color
El color de fondo del distintivo. Puede ser: white, yellow, blue, green, orange, red, purple, o gray-dark.
branding.icon
El nombre de del icono de Pluma de la v.4.28.0 a utilizar. Los iconos de marca se omiten, así como lo siguiente:
| coffee | columns | divide-circle | divide-square |
| divide | frown | hexagon | key |
| meh | mouse-pointer | smile | tool |
| x-octagon |
Aquí mostramos una lista exhaustiva de todos los iconos compatibles actualmente:
| activity | airplay | alert-circle | alert-octagon |
| alert-triangle | align-center | align-justify | align-left |
| align-right | anchor | aperture | archive |
| arrow-down-circle | arrow-down-left | arrow-down-right | arrow-down |
| arrow-down | arrow-left | arrow-left | arrow-right |
| arrow-up-circle | arrow-up-left | arrow-up-right | arrow-up |
| at-sign | award | bar-chart-2 | bar-chart |
| battery-charging | battery | bell-off | bell |
| bluetooth | bold | book-open | book |
| bookmark | box | briefcase | calendar |
| camera-off | camera | cast | check-circle |
| check-square | check | chevron-down | chevron-left |
| chevron-right | chevron-up | chevrons-down | chevrons-left |
| chevrons-right | chevrons-up | circle | clipboard |
| clock | cloud-drizzle | cloud-lightning | cloud-off |
| cloud-rain | cloud-snow | cloud | code |
| command | compass | copy | corner-down-left |
| corner-down-right | corner-left-down | corner-left-up | corner-right-down |
| corner-right-up | corner-up-left | corner-up-right | cpu |
| credit-card | crop | crosshair | database |
| delete | disc | dollar-sign | download-cloud |
| download | droplet | edit-2 | edit-3 |
| edit | external-link | eye-off | eye |
| fast-forward | feather | file-minus | |
| file-plus | file-text | file | film |
| filter | marcador | folder-minus | folder-plus |
| folder | gift | git-branch | git-commit |
| git-merge | git-pull-request | globe | grid |
| hard-drive | hash | headphones | heart |
| help-circle | home | image | inbox |
| info | italic | layers | layout |
| life-buoy | link-2 | link | list |
| loader | lock | log-in | log-out |
| map-pin | map | maximize-2 | |
| maximize | menu | message-circle | message-square |
| mic-off | mic | minimize-2 | minimize |
| minus-circle | minus-square | minus | monitor |
| moon | more-horizontal | more-vertical | move |
| music | navigation-2 | navigation | octagon |
| package | paperclip | pause-circle | pause |
| percent | phone-call | phone-forwarded | phone-incoming |
| phone-missed | phone-off | phone-outgoing | phone |
| pie-chart | play-circle | play | plus-circle |
| plus-square | plus | power | |
| printer | radio | refresh-ccw | refresh-cw |
| repeat | rewind | rotate-ccw | rotate-cw |
| rss | guardar | scissors | search |
| send | server | settings | share-2 |
| share | shield-off | shield | shopping-bag |
| shopping-cart | shuffle | sidebar | skip-back |
| skip-forward | slash | sliders | smartphone |
| speaker | square | star | stop-circle |
| sun | sunrise | sunset | tablet |
| tag | target | terminal | thermometer |
| thumbs-down | thumbs-up | toggle-left | toggle-right |
| trash-2 | trash | trending-down | trending-up |
| triangle | truck | tv | type |
| umbrella | underline | unlock | upload-cloud |
| upload | user-check | user-minus | user-plus |
| user-x | user | users | video-off |
| video | voicemail | volume-1 | volume-2 |
| volume-x | volume | watch | wifi-off |
| wifi | wind | x-circle | x-square |
| x | zap-off | zap | zoom-in |
| zoom-out |