Sintaxis de metadatos para Acciones 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 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. 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: Las acciones que usan required: true no devolverán automáticamente un error si no se especifica la entrada.

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, 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. Con acciones compuestas, puede usar inputs Acceso a información contextual sobre ejecuciones de flujo de trabajo para acceder a las entradas de acción.

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 está cerrar 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 "Acceso a información contextual sobre ejecuciones de flujo de trabajo".

`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 v20

runs:
  using: 'node20'
  main: 'main.js'

`runs.using` para acciones de JavaScript

Obligatorio Tiempo de ejecución utilizado para ejecutar el código especificado en main.

Use node20 para Node.js v20.

`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: 'node20'
  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: 'node20'
  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 "Acceso a información contextual sobre ejecuciones de flujo de trabajo".

`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 "Evaluación de expresiones en flujos de trabajo y acciones".

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 «Evaluación de expresiones en flujos de trabajo y acciones».

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 «Acceso a información contextual sobre ejecuciones de flujo de trabajo».

`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` 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, HOMEo 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 Dockerfilelocal 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'

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-left-circle
arrow-left
arrow-right-circle
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
mail
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
pocket
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
table
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

Sintaxis de metadatos para Acciones de GitHub

En este artículo