Nota: Actualmente los ejecutores hospedados en GitHub no se admiten en GitHub Enterprise Server. Puede ver más información sobre la compatibilidad futura planeada en GitHub public roadmap.
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 no está familiarizado con YAML, puede leer "Aprender YAML en cinco minutos".
name
Obligatorio Nombre de la acción. GitHub muestra name
en la pestaña Acciones para ayudar a identificar visualmente las acciones en cada trabajo.
author
Opcional Nombre del creador de la acción.
description
Obligatorio Descripción breve de la acción.
inputs
Opcional Los parámetros de entrada permiten especificar los datos que la acción espera 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
En este ejemplo se configuran dos entradas: num-octocats
y octocat-eye-color
. La entrada num-octocats
no es necesaria y toma 1
como valor predeterminado. La entrada octocat-eye-color
sí es necesaria y no tiene valor predeterminado.
Nota: Los flujos de trabajo que usan required: true
no devuelven automáticamente un error si no se especifica la entrada para los eventos que desencadenan automáticamente ejecuciones del flujo de trabajo. Si estableces required: true
en el archivo de flujo de trabajo y usas workflow_dispatch
para ejecutar manualmente el flujo de trabajo, debes especificar entradas en GitHub. Para obtener más información, vea «Eventos que desencadenan flujos de trabajo».
Los archivos de flujo de trabajo que utilizan esta acción deben usar la palabra clave with
para establecer un valor de entrada para octocat-eye-color
. Para obtener más información sobre la sintaxis with
, consulta "Sintaxis del flujo de trabajo para Acciones de GitHub".
inputs:
num-octocats:
description: 'Number of Octocats'
required: false
default: '1'
octocat-eye-color:
description: 'Eye color of the Octocats'
required: true
Al especificar una entrada en un archivo de flujo de trabajo o usar 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úsculas y reemplaza los espacios con caracteres _
.
Si la acción se escribe mediante una composición, no obtendrá INPUT_<VARIABLE_NAME>
automáticamente. Si la conversión no ocurre, puedes cambiar estas entradas manualmente.
Para acceder a la variable de entorno en una acción de contenedor de Docker, debe pasar la entrada mediante la palabra clave args
en el archivo de metadatos de la acción. Para más información sobre el archivo de metadatos de la acción para acciones de contenedor de Docker, consulta "Creación de una acción de contenedor de Docker".
Por ejemplo, si en un flujo de trabajo se han definido las entradas num-octocats
y octocat-eye-color
, el código de acción podría leer los valores de las entradas mediante las variables de entorno INPUT_NUM-OCTOCATS
y INPUT_OCTOCAT-EYE-COLOR
.
inputs.<input_id>
Obligatorio Identificador string
que se va a asociar a la entrada. El valor de <input_id>
es un mapa de los metadatos de la entrada. <input_id>
debe ser un identificador único dentro del objeto inputs
. <input_id>
debe empezar con una letra o _
, y solo puede contener caracteres alfanuméricos -
o _
.
inputs.<input_id>.description
Obligatorio Descripción string
del parámetro de entrada.
inputs.<input_id>.required
Opcional Un valor boolean
para indicar si la acción necesita el parámetro de entrada. Se establece en true
cuando el parámetro es obligatorio.
inputs.<input_id>.default
Opcional Un valor 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 usa el parámetro de entrada, string
se registra 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 acciones de contenedor de Docker y JavaScript
Opcional Los parámetros de salida permiten declarar datos que establece una acción. 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.
Las salidas son cadenas Unicode y pueden tener un máximo de 1 MB. El total de salidas de una ejecución de flujo de trabajo puede tener un máximo de 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 sobre cómo establecer salidas en una acción, consulta "Comandos de flujo de trabajo para Acciones de GitHub".
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>
Obligatorio Identificador string
que se va a asociar a la salida. El valor de <output_id>
es un mapa de los metadatos de la salida. <output_id>
debe ser un identificador único dentro del objeto outputs
. <output_id>
debe empezar con una letra o _
, y solo puede contener caracteres alfanuméricos -
o _
.
outputs.<output_id>.description
Obligatorio Descripción string
del parámetro de salida.
outputs
para acciones compuestas
Opcional outputs
usa los mismos parámetros que outputs.<output_id>
y outputs.<output_id>.description
(vea"outputs
para acciones de contenedor de Docker y JavaScript"), pero también incluye el token value
.
Las salidas son cadenas Unicode y pueden tener un máximo de 1 MB. El total de salidas de una ejecución de flujo de trabajo puede tener un máximo de 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 "random-id=$(echo $RANDOM)" >> $GITHUB_OUTPUT
shell: bash
outputs.<output_id>.value
Obligatorio Valor al que se asignará el parámetro de salida. Puede establecerlo en string
o en una expresión o con contexto. Por ejemplo, puede usar el contexto steps
para establecer el valor value
de una salida en el valor de salida de un paso.
Para más información sobre cómo usar la sintaxis de contexto, consulta "Contextos".
runs
Obligatorio Especifica si es una acción de JavaScript, una acción compuesta o una acción de contenedor de Docker y cómo se ejecut.
runs
para acciones de JavaScript
Obligatorio Configura la ruta al código de la acción y el tiempo de ejecución que se usa para ejecutar el código.
Ejemplo: Usar Node.js v16
runs:
using: 'node16'
main: 'main.js'
runs.using
para acciones de JavaScript
Obligatorio Tiempo de ejecución utilizado para ejecutar el código especificado en main
.
- Use
node16
para Node.js v16.
runs.main
Obligatorio El archivo que contiene el código de la acción. El tiempo de ejecución especificado en using
ejecuta este archivo.
runs.pre
Opcional Permite ejecutar un script al principio de un trabajo, antes de que comience la acción main:
. Por ejemplo, puede usar pre:
para ejecutar un script de configuración de requisitos previos. El tiempo de ejecución especificado con la sintaxis using
ejecutará este archivo. La acción pre:
siempre se ejecuta de forma predeterminada, pero puede invalidarla mediante runs.pre-if
.
En este ejemplo, la acción pre:
ejecuta un script denominado setup.js
:
runs:
using: 'node16'
pre: 'setup.js'
main: 'index.js'
post: 'cleanup.js'
runs.pre-if
Opcional Permite definir condiciones para la ejecución de la acción pre:
. La acción pre:
solo se ejecutará si se cumplen las condiciones de pre-if
. Si no se establece, el valor predeterminado de pre-if
es always()
. En pre-if
, las funciones de comprobación de estado se evalúan con el estado del trabajo, no con el de la propia acción.
Tenga en cuenta que el contexto step
no está disponible, ya que todavía no se ha ejecutado ningún paso.
En este ejemplo, cleanup.js
solo se ejecuta en ejecutores basados en Linux:
pre: 'cleanup.js'
pre-if: runner.os == 'linux'
runs.post
Opcional Permite ejecutar un script al final de un trabajo una vez que se complete la acción main:
. Por ejemplo, puede usar post:
para finalizar algunos procesos o eliminar archivos innecesarios. El tiempo de ejecución especificado con la sintaxis using
ejecutará este archivo.
En este ejemplo, la acción post:
ejecuta un script denominado cleanup.js
:
runs:
using: 'node16'
main: 'index.js'
post: 'cleanup.js'
La acción post:
siempre se ejecuta de forma predeterminada, pero puede invalidarla mediante post-if
.
runs.post-if
Opcional Permite definir condiciones para la ejecución de la acción post:
. La acción post:
solo se ejecutará si se cumplen las condiciones de post-if
. Si no se establece, el valor predeterminado de post-if
es always()
. En post-if
, las funciones de comprobación de estado se evalúan con el estado del trabajo, no con el de la propia acción.
Por ejemplo, cleanup.js
solo se ejecutará en ejecutores basados en Linux:
post: 'cleanup.js'
post-if: runner.os == 'linux'
runs
para acciones compuestas
Obligatorio Configura la ruta a la acción compuesta.
runs.using
para acciones compuestas
Obligatorio Debe establecer este valor en 'composite'
.
runs.steps
Obligatorio Pasos que tienes previsto ejecutar en esta acción. Pueden ser pasos run
o uses
.
runs.steps[*].run
Opcional Comando que quieres ejecutar. Puede estar insertado o ser un script en el repositorio de la acción:
runs:
using: "composite"
steps:
- run: ${{ github.action_path }}/test/script.sh
shell: bash
Como alternativa, puede usar $GITHUB_ACTION_PATH
:
runs:
using: "composite"
steps:
- run: $GITHUB_ACTION_PATH/script.sh
shell: bash
Para más información, consulta "Contextos".
runs.steps[*].shell
Opcional Shell donde quieres ejecutar el comando. Puedes usar cualquiera de los shells que se enumeran en «Sintaxis del flujo de trabajo para Acciones de GitHub». Es obligatorio si se establece run
.
runs.steps[*].if
Opcional Puede usar la condicional if
para impedir que se ejecute un paso si no se cumple una condición. Puedes usar cualquier contexto y expresión admitidos para crear un condicional.
Cuando se usan expresiones en un condicional if
, se puede omitir la sintaxis de la expresión ${{ }}
opcionalmente, porque GitHub Actions evalúa automáticamente el condicional if
como una expresión. Sin embargo, esta excepción no se aplica en todas partes.
Debe usar siempre la sintaxis de expresión ${{ }}
o escapar con ''
, ""
o ()
cuando la expresión comienza con !
, ya que !
es una notación reservada en formato YAML. Por ejemplo:
if: ${{ ! startsWith(github.ref, 'refs/tags/') }}
Para más información, consulta "Expresiones".
Ejemplo: Uso de contextos
Este paso solo se ejecuta cuando el tipo de evento es pull_request
y la acción del evento es unassigned
.
steps:
- run: echo This event is a pull request that had an assignee removed.
if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}
Ejemplo: Uso de funciones de comprobación de estado
my backup step
solo se ejecuta cuando se produce un error en el paso anterior de una acción compuesta. Para obtener más información, vea «Expresiones».
steps:
- name: My first step
uses: octo-org/action-name@main
- name: My backup step
if: ${{ failure() }}
uses: actions/heroku@1.0.0
runs.steps[*].name
Opcional Nombre del paso compuesto.
runs.steps[*].id
Opcional Identificador único para el paso. Puede usar id
para hacer referencia al paso en los contextos. Para obtener más información, vea «Contextos».
runs.steps[*].env
Opcional Establece una map
de variables de entorno solo para ese paso. Si quiere modificar la variable de entorno almacenada en el flujo de trabajo, use echo "{name}={value}" >> $GITHUB_ENV
en un paso compuesto.
runs.steps[*].working-directory
Opcional Especifica el directorio de trabajo donde se ejecuta el comando.
runs.steps[*].uses
Opcional Selecciona una acción que se ejecutará como parte de un paso en el trabajo. Una acción es una unidad de código reutilizable. Puede usar una acción definida en el mismo repositorio que el flujo de trabajo, un repositorio público o en una imagen de contenedor de Docker publicada.
Te recomendamos firmemente que incluyas la versión de la acción que estás utilizando y especifiques un número de etiqueta de la ref de Git, SHA o Docker. Si no especificas una versión, podrías interrumpir tus flujos de trabajo o provocar un comportamiento inesperado cuando el propietario de la acción publique una actualización.
- El uso del SHA de confirmación de una versión de acción lanzada es lo más seguro para la estabilidad y la seguridad.
- Usar la versión de acción principal específica te permite recibir correcciones críticas y parches de seguridad y al mismo tiempo mantener la compatibilidad. También asegura que tu flujo de trabajo aún debería funcionar.
- Puede ser conveniente utilizar la rama predeterminada de una acciòn, pero si alguien lanza una versiòn principal nueva con un cambio importante, tu flujo de trabajo podrìa fallar.
Algunas acciones necesitan entradas que debe establecer mediante la palabra clave with
. Revisa el archivo README de la acción para determinar las entradas requeridas.
runs:
using: "composite"
steps:
# Reference a specific commit
- uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3
# Reference the major version of a release
- uses: actions/checkout@v4
# Reference a specific version
- uses: actions/checkout@v4.2.0
# Reference a branch
- uses: actions/checkout@main
# References a subdirectory in a public GitHub repository at a specific branch, ref, or SHA
- uses: actions/aws/ec2@main
# References a local action
- uses: ./.github/actions/my-action
# References a docker public registry action
- uses: docker://gcr.io/cloud-builders/gradle
# Reference a docker image published on docker hub
- uses: docker://alpine:3.8
runs.steps[*].with
Opcional Objeto map
de los parámetros de entrada definidos por la acción. Cada parámetro de entrada es un par clave/valor. Para obtener más información, consulta Ejemplo: Especificación de entradas.
runs:
using: "composite"
steps:
- name: My first step
uses: actions/hello_world@main
with:
first_name: Mona
middle_name: The
last_name: Octocat
runs.steps[*].continue-on-error
Opcional Impide que se produzca un error en la acción cuando se produce un error en un paso. Establézcalo en true
para permitir que la acción se supere cuando se produzca un error en este paso.
runs
para acciones de contenedor de Docker
Obligatorio Configura la imagen usada para la acción de contenedor 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
para acciones de contenedor de Docker
Obligatorio Debe establecer este valor en 'docker'
.
runs.pre-entrypoint
Opcional Permite ejecutar un script antes de que comience la acción entrypoint
. Por ejemplo, puede usar pre-entrypoint:
para ejecutar un script de configuración de requisitos previos. GitHub Actions usa docker run
para iniciar esta acción, y ejecuta el script dentro de un contenedor nuevo que usa la misma imagen base. Esto significa que el estado en tiempo de ejecución es diferente del contenedor entrypoint
principal y que a los estados que necesita se debe acceder desde el área de trabajo, HOME
o como una variable STATE_
. La acción pre-entrypoint:
siempre se ejecuta de forma predeterminada, pero puede invalidarla mediante runs.pre-if
.
El tiempo de ejecución especificado con la sintaxis using
ejecutará este archivo.
En este ejemplo, la acción pre-entrypoint:
ejecuta un script denominado setup.sh
:
runs:
using: 'docker'
image: 'Dockerfile'
args:
- 'bzz'
pre-entrypoint: 'setup.sh'
entrypoint: 'main.sh'
runs.image
Obligatorio Imagen de Docker que se usará como contenedor para ejecutar la acción. El valor puede ser el nombre de la imagen base de Docker, un Dockerfile
local en el repositorio o una imagen pública en Docker Hub u otro registro. Para hacer referencia a un Dockerfile
local al repositorio, el archivo debe tener el nombre Dockerfile
y debe usar una ruta relativa al archivo de metadatos de la acción. La aplicación docker
ejecutará este archivo.
runs.env
Opcional Especifica una asignación de clave-valor de las variables de entorno que se van a establecer en el entorno de contenedor.
runs.entrypoint
Opcional Invalida ENTRYPOINT
de Docker en Dockerfile
, o bien lo establece si todavía no se ha especificado uno. Use entrypoint
cuando Dockerfile
no especifique ENTRYPOINT
o si quiere invalidar la instrucción ENTRYPOINT
. Si omite entrypoint
, se ejecutarán los comandos que especifique en la instrucción ENTRYPOINT
de Docker. La instrucción ENTRYPOINT
de Docker tiene un formato shell y otro exec. En la documentación de ENTRYPOINT
de Docker se recomienda usar el formato exec de la instrucción ENTRYPOINT
.
Para obtener más información sobre cómo se ejecuta entrypoint
, consulta "Soporte de Dockerfile para GitHub Actions".
runs.post-entrypoint
Opcional Permite ejecutar un script de limpieza una vez que se complete la acción runs.entrypoint
. GitHub Actions usa docker run
para iniciar esta acción. Como GitHub Actions ejecuta el script dentro de un contenedor nuevo con la misma imagen base, el estado de tiempo de ejecución es diferente del contenedor entrypoint
principal. Puede acceder a cualquier estado que necesite en el área de trabajo, HOME
o como una variable STATE_
. La acción post-entrypoint:
siempre se ejecuta de forma predeterminada, pero puede invalidarla mediante runs.post-if
.
runs:
using: 'docker'
image: 'Dockerfile'
args:
- 'bzz'
entrypoint: 'main.sh'
post-entrypoint: 'cleanup.sh'
runs.args
Opcional Matriz de cadenas que definen las entradas de un contenedor de Docker. Las entradas pueden incluir cadenas codificadas de forma rígida. GitHub pasa args
al valor ENTRYPOINT
del contenedor cuando se inicia.
args
se usan en lugar de la instrucción CMD
en Dockerfile
. Si usa CMD
en Dockerfile
, utilice las instrucciones ordenadas por preferencia:
- En el documento se necesitaban argumentos en el archivo Léame de la acción y omitirlos de la instrucción
CMD
. - Use los valores predeterminados que permiten usar la acción sin especificar
args
. - Si la acción expone una marca
--help
, o algo similar, úselo para que la acción se documente de forma automática.
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 el atributo entrypoint
está establecido en "sh -c"
, args
se ejecutará en un shell de comandos. Como alternativa, si en Dockerfile
se usa ENTRYPOINT
para ejecutar el mismo comando ("sh -c"
), 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 "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
Opcional Puedes usar un color y un icono de pluma con el fin de crear una notificación para personalizar y distinguir la acción. Los distintivos se muestran junto al nombre de la 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
Nombre del icono de pluma v4.28.0 que se va a usar.
Iconos omitidos
Se omiten los iconos de marca y todos los iconos siguientes.
- café
- columnas
- divide-circle
- divide-square
- divide
- frown
- hexagon
- key
- meh
- mouse-pointer
- smile
- herramienta
- x-octagon
Lista exhaustiva de todos los iconos admitidos actualmente
- activity
- airplay
- alert-circle
- alert-octagon
- alert-triangle
- align-center
- align-justify
- align-left
- align-right
- delimitador
- aperture
- archivar
- 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
- campana
- Bluetooth
- negrita
- book-open
- libro
- marcador
- Box
- briefcase
- calendario
- camera-off
- cámara
- Conversión
- check-circle
- check-square
- check
- chevron-down
- chevron-left
- chevron-right
- chevron-up
- chevrons-down
- chevrons-left
- chevrons-right
- chevrons-up
- circle
- Portapapeles
- clock
- cloud-drizzle
- cloud-lightning
- cloud-off
- cloud-rain
- cloud-snow
- cloud
- código
- 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
- descarga
- droplet
- edit-2
- edit-3
- edición
- external-link
- eye-off
- eye
- fast-forward
- feather
- file-minus
- file-plus
- file-text
- archivo
- film
- filter
- Marca
- 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
- imagen
- inbox
- info
- cursiva
- Capas
- diseño
- life-buoy
- link-2
- link
- list
- Cargador
- bloquear
- log-in
- log-out
- map-pin
- mapa
- maximize-2
- maximize
- menú
- message-circle
- message-square
- mic-off
- mic
- minimize-2
- minimize
- minus-circle
- minus-square
- minus
- monitor
- moon
- more-horizontal
- more-vertical
- mover
- music
- navigation-2
- navegación
- octagon
- paquete
- 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
- potencia
- printer
- radio
- refresh-ccw
- refresh-cw
- repeat
- rewind
- rotate-ccw
- rotate-cw
- rss
- Guardar
- scissors
- paquetes Bower
- Enviar
- server
- configuración
- share-2
- Compartir
- shield-off
- shield
- shopping-bag
- shopping-cart
- shuffle
- barra lateral
- skip-back
- skip-forward
- slash
- controles deslizantes
- smartphone
- speaker (altavoz)
- square
- star (asterisco)
- stop-circle
- sun
- sunrise
- puesta de sol
- tableta
- etiqueta
- Destino
- terminal
- thermometer
- thumbs-down
- thumbs-up
- toggle-left
- toggle-right
- trash-2
- trash
- trending-down
- trending-up
- triangle
- camión
- tv
- type
- umbrella (paraguas)
- subrayado
- desbloquear
- upload-cloud
- upload
- user-check
- user-minus
- user-plus
- user-x
- usuario
- users
- video-off
- video
- voicemail
- volume-1
- volume-2
- volume-x
- volumen
- watch
- wifi-off
- wifi
- wind
- x-circle
- x-square
- x
- zap-off
- zap
- zoom-in
- zoom-out