Skip to main content
Publicamos actualizaciones para la documentación con frecuencia y es posible que aún se esté traduciendo esta página. Para obtener la información más reciente, consulta la documentación en inglés.

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.

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 tendrá como valor predeterminado un valor de "1"; octocat-eye-color es obligatorio y no tiene ningún valor predeterminado. Los archivos de flujo de trabajo que utilizan esta acción deben usar la palabra clave with a fin de establecer un valor de entrada para octocat-eye-color. Para más información sobre la sintaxis with, vea "Sintaxis de flujo de trabajo para GitHub Actions".

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, vea "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 más información sobre el establecimiento de salidas en una acción, vea "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>

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 "::set-output name=random-id::$(echo $RANDOM)"
      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, vea "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: Uso de Node.js v16

runs:
  using: 'node16'
  main: 'main.js'

runs.using

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

  • Usa node12 para Node.js v12.
  • 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

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, vea "github context".

runs.steps[*].shell

Opcional Shell donde quieres ejecutar el comando. Puede usar cualquiera de los shells que se enumeran aquí. 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.

Al usar expresiones en una condicional if, puede omitir la sintaxis de la expresión (${{ }}) porque GitHub evalúa de forma automática la condicional if como una expresión. Para más información, vea "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 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 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@a81bbbf8298c0fa03ea29cdc473d45769f953675
    # Reference the major version of a release
    - uses: actions/checkout@v3
    # Reference a specific version
    - uses: actions/checkout@v3.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

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 más información sobre cómo se ejecuta entrypoint, vea "Compatibilidad de Dockerfile con 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 más información sobre el uso de la instrucción CMD con GitHub Actions, vea "Compatibilidad de Dockerfile con 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. Los iconos de marca se omiten, así como lo siguiente:

café columnas divide-circle divide-square
divide frown hexagon key
meh mouse-pointer smile herramienta
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 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