Skip to main content

Sintaxis de metadatos para Acciones de GitHub

Puedes crear acciones para realizar tareas en tu repositorio. Las acciones requieren un archivo de metadatos que use la sintaxis YAML.

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.com. 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 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 "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 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:

  1. En el documento se necesitaban argumentos en el archivo Léame de la acción y omitirlos de la instrucción CMD.
  2. Use los valores predeterminados que permiten usar la acción sin especificar args.
  3. 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
  • 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
  • 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