Sintaxis del flujo de trabajo para Acciones de GitHub

Acerca de la sintaxis de YAML para flujos de trabajo

Los archivos de flujo de trabajo usan la sintaxis de YAML y deben tener una extensión de archivo .yml o .yaml. Si no está familiarizado con YAML y quiere obtener más información, vea "Aprenda YAML en Y minutos".

Debe almacenar los archivos de flujo de trabajo en el directorio .github/workflows del repositorio.

name

Nombre del flujo de trabajo. GitHub muestra los nombres de los flujos de trabajo en la pestaña "Acciones" del repositorio. Si omite name, GitHub lo establece en la ruta de acceso del archivo de flujo de trabajo relativa a la raíz del repositorio.

run-name

Nombre de las ejecuciones de flujo de trabajo generadas a partir del flujo de trabajo. GitHub muestra el nombre de ejecución del flujo de trabajo en la lista de ejecuciones de flujo de trabajo en la pestaña "Acciones" del repositorio. Si run-name se omite o si es solo un espacio en blanco, el nombre de la ejecución se establece en la información específica del evento para la ejecución del flujo de trabajo. Por ejemplo, para un flujo de trabajo que desencadena un evento push o pull_request, se establece como mensaje de confirmación.

Este valor puede incluir expresiones y puede hacer referencia a los contextos github y inputs.

Ejemplo de run-name

run-name: Deploy to ${{ inputs.deploy_target }} by @${{ github.actor }}

on

Para desencadenar automáticamente un flujo de trabajo, use on para definir qué eventos pueden hacer que se ejecute el flujo de trabajo. Para obtener una lista de eventos disponibles, consulte "Eventos que desencadenan flujos de trabajo".

Puedes definir eventos sencillos o múltiples que puedan activar un flujo de trabajo o configurar una programación. También puedes restringir la ejecución de un flujo de trabajo para que solo ocurra para archivos, etiquetas o cambios de rama específicos. Estas opciones se describen en las secciones siguientes.

Utilizar un evento simple

Por ejemplo, un flujo de trabajo con el siguiente valor de on se ejecutará cuando se realice una subida a cualquier rama en el repositorio del flujo de trabajo:

on: push

Utilizar eventos múltiples

Puedes especificar eventos sencillos o múltiples. Por ejemplo, un flujo de trabajo con el siguiente valor de on se ejecutará cuando se realice una inserción en cualquier rama del repositorio o cuando alguien lo bifurque:

on: [push, fork]

Si especificas eventos múltiples, únicamente uno de ellos necesitará ocurrir para que se active tu flujo de trabajo. Si ocurren eventos múltiples de activación para tu flujo de trabajo al mismo tiempo, se activarán las ejecuciones de flujo de trabajo múltiples.

Utilizar tipos de actividad

Algunos eventos tienen tipos de actividad que te proporcionan más control sobre cuándo debería ejecutarse tu flujo de trabajo. Use on.<event_name>.types para definir el tipo de actividad de evento que desencadenará una ejecución de flujo de trabajo.

Por ejemplo, el evento issue_comment tiene los tipos de actividad created, edited y deleted. Si el flujo de trabajo desencadena el evento label, se ejecutará cada vez que se cree, edite o elimine una etiqueta. Si especifica el tipo de actividad created para el evento label, el flujo de trabajo se ejecutará cuando se cree una etiqueta pero no cuando se edite o elimine.

on:
  label:
    types:
      - created

Si especificas tipos de actividad múltiples, solo uno de ellos necesitará ocurrir para que se active tu flujo de trabajo. Si ocurren tipos de actividad de eventos activadores múltiples al mismo tiempo para tu flujo de trabajo, se activarán ejecuciones de flujo de trabajo múltiples. Por ejemplo, el siguiente flujo de trabajo se activa cuando se abre o etiqueta una propuesta. Si se abre una propuesta con dos etiquetas, iniciarán tres ejecuciones de flujo de trabajo: una para el evento de la propuesta abierta y dos para los eventos etiquetados de las dos propuestas.

on:
  issues:
    types:
      - opened
      - labeled

Para más información sobre cada evento y sus tipos de actividad, vea "Eventos que desencadenan flujos de trabajo".

Utilizar filtros

Algunos eventos tienen filtros que te dan más control sobre qué flujo de trabajo debería ejecutarse.

Por ejemplo, el evento push tiene un filtro branches que hace que el flujo de trabajo solo se ejecute cuando se realice una inserción en una rama que coincida con el filtro branches, en lugar de cuando se produzca cualquier inserción.

on:
  push:
    branches:
      - main
      - 'releases/**'

Utilizar los tipos de actividad y filtros con eventos múltiples

Si especificas los tipos de actividad o filtros para un evento y tu flujo de trabajo activa eventos múltiples, deberás configurar cada uno de ellos por separado. Debe agregar dos puntos (:) a todos los eventos, incluidos aquellos sin configuración.

Por ejemplo, un flujo de trabajo con el valor on siguiente se ejecutará cuando:

• Se crea una etiqueta
• Se hace una inserción a la rama main en el repositorio.
• Se hace una subida a la rama habilitada por GitHub Pages

on:
  label:
    types:
      - created
  push:
    branches:
      - main
  page_build:

on.<event_name>.types

Usa on.<event_name>.types para definir el tipo de actividad que desencadenará una ejecución de flujo de trabajo. La mayoría de los eventos GitHub son activados por más de un tipo de actividad. Por ejemplo, label se desencadena cuando una etiqueta es created, edited o deleted. La palabra clave types te permite reducir la actividad que hace que se ejecute el flujo de trabajo. Cuando solo un tipo de actividad desencadena un evento de webhook, la palabra clave types no es necesaria.

Puedes usar una matriz de eventos types. Para obtener más información sobre cada evento y sus tipos de actividad, consulta "Eventos que desencadenan flujos de trabajo".

on:
  label:
    types: [created, edited]

on.<pull_request|pull_request_target>.<branches|branches-ignore>

Al usar los eventos pull_request y pull_request_target, puede configurar un flujo de trabajo a fin de que solo se ejecute para las solicitudes de incorporación de cambios destinadas a ramas específicas.

Use el filtro branches cuando quiera incluir patrones de nombre de rama, o bien cuando quiera incluirlos y excluirlos. Use el filtro branches-ignore cuando solo quiera excluir patrones de nombre de rama. No puede usar los filtros branches y branches-ignore para el mismo evento de un flujo de trabajo.

Si define branches/branches-ignore y paths, el flujo de trabajo solo se ejecutará cuando se cumplan los dos filtros.

Las palabras clave branches y branches-ignore aceptan patrones globales que usan caracteres como *, **, +, ? y !, entre otros, para que coincidan con más de un nombre de rama. Si un nombre contiene cualquiera de estos caracteres y quiere una coincidencia literal, necesita escapar a cada uno de estos caracteres especiales con \. Para obtener más información sobre los patrones globales, consulte la "Hoja de referencia rápida de patrones de filtro".

Ejemplo: Incluir ramas

Los patrones definidos en branches se evalúan con el nombre de referencia de Git. Por ejemplo, el siguiente flujo de trabajo se ejecutará siempre que exista un evento pull_request para una solicitud de incorporación de cambios destinada a:

• Una rama denominada main (refs/heads/main)
• Una rama denominada mona/octocat (refs/heads/mona/octocat)
• Una rama cuyo nombre comienza por releases/, como releases/10 (refs/heads/releases/10)

on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches:    
      - main
      - 'mona/octocat'
      - 'releases/**'

Ejemplo: Excluir ramas

Cuando un patrón coincide con el patrón branches-ignore, el flujo de trabajo no se ejecutará. Los patrones definidos en branches se evalúan con el nombre de referencia de Git. Por ejemplo, el siguiente flujo de trabajo se ejecutará siempre que haya un evento de pull_request a menos de que la solicitud de incorporación de cambios esté destinada a:

• Una rama denominada mona/octocat (refs/heads/mona/octocat)
• Una rama cuyo nombre coincide con releases/**-alpha, como releases/beta/3-alpha (refs/heads/releases/beta/3-alpha)

on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches-ignore:    
      - 'mona/octocat'
      - 'releases/**-alpha'

Ejemplo: Incluir y excluir ramas

No puede usar branches y branches-ignore para filtrar el mismo evento en un único flujo de trabajo. Si quiere tanto incluir como excluir patrones de rama para un solo evento, utilice el filtro branches junto con el carácter ! para indicar qué ramas deberían excluirse.

Si define una rama con el carácter !, también tendrá que definir al menos otra sin el carácter !. Si solo quiere excluir ramas, use branches-ignore en su lugar.

El orden en que defines los patrones importa.

• Un patrón negativo coincidente (con el prefijo !) después de una coincidencia positiva hará que se excluya la referencia de Git.
• Un patrón positivo de coincidencia luego de una coincidencia negativa volverá a incluir la ref de Git.

El flujo de trabajo siguiente se ejecutará en eventos pull_request para las solicitudes de incorporación de cambios que tienen como destino releases/10 o releases/beta/mona, pero no para las que tienen como destino releases/10-alpha o releases/beta/3-alpha porque el patrón negativo !releases/**-alpha sigue el patrón positivo.

on:
  pull_request:
    branches:    
      - 'releases/**'
      - '!releases/**-alpha'

on.push.<branches|tags|branches-ignore|tags-ignore>

Al usar el evento push, puede configurar un flujo de trabajo para que se ejecute en ramas o etiquetas específicas.

Use el filtro branches cuando quiera incluir patrones de nombre de rama, o bien cuando quiera incluirlos y excluirlos. Use el filtro branches-ignore cuando solo quiera excluir patrones de nombre de rama. No puede usar los filtros branches y branches-ignore para el mismo evento de un flujo de trabajo.

Use el filtro tags cuando quiera incluir los patrones de nombre de etiqueta, o bien cuando quiera incluirlos y excluirlos. Use el filtro tags-ignore cuando solo quiera excluir patrones de nombre de etiqueta. No puede usar los filtros tags y tags-ignore para el mismo evento de un flujo de trabajo.

Si solo define tags/tags-ignore o branches/branches-ignore, el flujo de trabajo no se ejecutará para eventos que afecten a la referencia de Git no definida. Si no define tags/tags-ignore ni branches/branches-ignore, el flujo de trabajo se ejecutará para eventos que afecten a ramas o etiquetas. Si define branches/branches-ignore y paths, el flujo de trabajo solo se ejecutará cuando se cumplan los dos filtros.

Las palabras clave branches, branches-ignore, tags y tags-ignore aceptan patrones globales que usan caracteres como *, **, +, ?, ! y otros para que coincidan con más de un nombre de rama o etiqueta. Si un nombre contiene cualquiera de estos caracteres y quiere una coincidencia literal, necesita escapar a cada uno de estos caracteres especiales con \. Para obtener más información sobre los patrones globales, consulte la "Hoja de referencia rápida de patrones de filtro".

Ejemplo: Incluyendo ramas y etiquetas

Los patrones definidos en branches y tags se evalúan con el nombre de referencia de Git. Por ejemplo, el siguiente flujo de trabajo se ejecutaría siempre que hubiera un evento push para:

• Una rama denominada main (refs/heads/main)
• Una rama denominada mona/octocat (refs/heads/mona/octocat)
• Una rama cuyo nombre comienza por releases/, como releases/10 (refs/heads/releases/10)
• Una etiqueta denominada v2 (refs/tags/v2)
• Una etiqueta cuyo nombre comienza por v1., como v1.9.1 (refs/tags/v1.9.1)

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches:    
      - main
      - 'mona/octocat'
      - 'releases/**'
    # Sequence of patterns matched against refs/tags
    tags:        
      - v2
      - v1.*

Ejemplo: Excluir ramas y etiquetas

Cuando un patrón coincide con el patrón branches-ignore o tags-ignore, el flujo de trabajo no se ejecutará. Los patrones definidos en branches y tags se evalúan con el nombre de referencia de Git. Por ejemplo, el siguiente flujo de trabajo se ejecutará siempre que haya un evento push, a menos que el evento push sea para:

• Una rama denominada mona/octocat (refs/heads/mona/octocat)
• Una rama cuyo nombre coincide con releases/**-alpha, como beta/3-alpha (refs/releases/beta/3-alpha)
• Una etiqueta denominada v2 (refs/tags/v2)
• Una etiqueta cuyo nombre comienza por v1., como v1.9 (refs/tags/v1.9)

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches-ignore:    
      - 'mona/octocat'
      - 'releases/**-alpha'
    # Sequence of patterns matched against refs/tags
    tags-ignore:        
      - v2
      - v1.*

Ejemplo: incluir y excluir ramas y etiquetas

No puede usar branches y branches-ignore para filtrar el mismo evento en un único flujo de trabajo. Del mismo modo, no puede usar tags y tags-ignore para filtrar el mismo evento en un único flujo de trabajo. Si quiere tanto incluir como excluir patrones de rama o etiqueta para un solo evento, use el filtro branches o tags junto con el carácter ! para indicar qué ramas o etiquetas se deberían excluir.

Si define una rama con el carácter !, también tendrá que definir al menos otra sin el carácter !. Si solo quiere excluir ramas, use branches-ignore en su lugar. Del mismo modo, si define una etiqueta con el carácter !, también tendrá que definir al menos otra sin el carácter !. Si solo quiere excluir etiquetas, use tags-ignore en su lugar.

El orden en que defines los patrones importa.

• Un patrón negativo coincidente (con el prefijo !) después de una coincidencia positiva hará que se excluya la referencia de Git.
• Un patrón positivo de coincidencia luego de una coincidencia negativa volverá a incluir la ref de Git.

El siguiente flujo de trabajo se ejecutará en inserciones en releases/10 o releases/beta/mona, pero no en releases/10-alpha o releases/beta/3-alpha, porque el patrón !releases/**-alpha negativo sigue el patrón positivo.

on:
  push:
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

on.<push|pull_request|pull_request_target>.<paths|paths-ignore>

Al usar los eventos push y pull_request, puedes configurar un flujo de trabajo para su ejecución en función de las rutas de acceso de archivo que se cambien. Los filtros de ruta no se evalúan para subidas de etiquetas.

Usa el filtro paths cuando quieras incluir patrones de ruta de acceso de archivos o cuando quieras tanto incluirlos como excluirlos. Usa el filtro paths-ignore cuando solo quieras excluir patrones de ruta de acceso de archivos. No puede usar los filtros paths y paths-ignore para el mismo evento de un flujo de trabajo.

Si defines branches/branches-ignore y paths, el flujo de trabajo solo se ejecutará cuando se cumplan ambos filtros.

Las palabras clave paths y paths-ignore aceptan patrones globales que usan los caracteres comodín * y ** para coincidir con más de un nombre de ruta de acceso. Para obtener más información, consulta el "Sintaxis del flujo de trabajo para Acciones de GitHub".

Ejemplo: Incluyendo rutas

Si al menos una ruta de acceso coincide con un patrón en el filtro paths, se ejecuta el flujo de trabajo. Por ejemplo, el flujo de trabajo siguiente se ejecutaría cada vez que envíes cambios de un archivo JavaScript (.js).

on:
  push:
    paths:
      - '**.js'

Ejemplo: Exclusión de rutas de acceso

Cuando todos los nombres de ruta de acceso coincidan con los patrones de paths-ignore, el flujo de trabajo no se ejecutará. Si alguno de los nombres de ruta de acceso no coincide con los patrones de paths-ignore, aunque algunos nombres de ruta coincidan con estos, el flujo de trabajo se ejecutará.

Un flujo de trabajo con el siguiente filtro de ruta de acceso solo se ejecutará en los eventos push que incluyan al menos un archivo externo al directorio docs en la raíz del repositorio.

on:
  push:
    paths-ignore:
      - 'docs/**'

Ejemplo: Inclusión y exclusión de rutas de acceso

No puedes usar paths y paths-ignore para filtrar el mismo evento en un único flujo de trabajo. Si quieres tanto incluir como excluir patrones de ruta de acceso para un solo evento, usa el filtro paths junto con el carácter ! para indicar qué rutas de acceso se deben excluir.

Si defines una ruta de acceso con el carácter !, también debes definir al menos una ruta de acceso sin el carácter !. Si solo quieres excluir rutas de acceso, usa paths-ignore en su lugar.

El orden en que defines los patrones importa:

• El tener una coincidencia de patrón negativo (con el prefijo !) después de una coincidencia positiva hará que se excluya la ruta de acceso.
• Un patrón de coincidencia positiva luego de una coincidencia negativa excluirá nuevamente la ruta.

Este ejemplo se ejecuta cada vez que el evento push incluye un archivo en el directorio sub-project o sus subdirectorios, a menos que el archivo esté en el directorio sub-project/docs. Por ejemplo, una inserción que haya cambiado sub-project/index.js o sub-project/src/index.js desencadenará una ejecución de flujo de trabajo, pero una inserción que solo cambie sub-project/docs/readme.md no lo hará.

on:
  push:
    paths:
      - 'sub-project/**'
      - '!sub-project/docs/**'

Comparaciones de diferencias de Git

El filtro determina si un flujo de trabajo debe ejecutarse al evaluar los archivos modificados y ejecutarlos en comparación con la lista de paths-ignore o paths. Si no hay archivos modificados, no se ejecutará el flujo de trabajo.

GitHub genera la lista de archivos modificados usando diferencias de dos puntos para las subidas y de tres puntos para las solicitudes de extracción:

• Solicitudes de incorporación de cambios: las diferencias de tres puntos son una comparación entre la versión más reciente de la rama de tema y la confirmación en la que la rama de tema se sincronizó por última vez con la rama base.
• Inserción en ramas existentes: una diferencia de dos puntos compara los SHA base y principal directamente entre sí.
• Inserción en ramas nuevas: una diferencia de dos puntos comparada con el elemento primario del antecesor de la confirmación insertada más profunda.

Los diffs se limitan a 300 archivos. Si hay archivos que cambiaron y no se empataron en los primeros 300 archivos que devuelve el filtro, el flujo de trabajo no se ejecutará. Puede que necesites crear filtros más específicos para que el flujo de trabajo se ejecute automáticamente.

Para obtener más información, vea «Acerca de comparar ramas en solicitudes de extracción».

on.schedule

Puede usar on.schedule para definir una programación de tiempo para los flujos de trabajo. Puede programar un flujo de trabajo para que se ejecute a horas UTC específicas mediante la sintaxis cron de POSIX. Los flujos de trabajo programados se ejecutan en la confirmación más reciente en la rama base o en la rama por defecto. El intervalo más corto en el que puedes ejecutar flujos de trabajo programados es una vez cada 5 minutos.

Este ejemplo activa el flujo de trabajo diariamente a las 5:30 y 17:30 UTC:

on:
  schedule:
    # * is a special character in YAML so you have to quote this string
    - cron:  '30 5,17 * * *'

Varios eventos schedule pueden desencadenar un único flujo de trabajo. Puede acceder al evento de programación que desencadenó el flujo de trabajo mediante el contexto github.event.schedule. En este ejemplo se desencadena el flujo de trabajo para que se ejecute a las 5:30 UTC de lunes a jueves, pero omite el paso Not on Monday or Wednesday para el lunes y el miércoles.

on:
  schedule:
    - cron: '30 5 * * 1,3'
    - cron: '30 5 * * 2,4'

jobs:
  test_schedule:
    runs-on: ubuntu-latest
    steps:
      - name: Not on Monday or Wednesday
        if: github.event.schedule != '30 5 * * 1,3'
        run: echo "This step will be skipped on Monday and Wednesday"
      - name: Every time
        run: echo "This step will always run"

Para obtener más información sobre la sintaxis cron, consulte "Eventos que desencadenan flujos de trabajo".

on.workflow_call

Use on.workflow_call para definir las entradas y salidas de un flujo de trabajo reutilizable. También puedes mapear los secretos que están disponibles para el flujo de trabajo llamado. Para más información sobre los flujos de trabajo reutilizables, consulte "Reutilización de flujos de trabajo".

on.workflow_call.inputs

Al usar la palabra clave workflow_call, puede especificar opcionalmente las entradas que se pasan al flujo de trabajo llamado desde el flujo de trabajo que realiza la llamada. Para obtener más información sobre la palabra clave workflow_call, consulte "Eventos que desencadenan flujos de trabajo".

Además de los parámetros de entrada estándar que están disponibles, on.workflow_call.inputs necesita un parámetro type. Para más información, vea on.workflow_call.inputs.<input_id>.type.

Si no se establece un parámetro default, el valor predeterminado de la entrada es false para un valor booleano, 0 para un número y "" para una cadena.

Dentro del flujo de trabajo llamado, puede usar el contexto inputs para hacer referencia a una entrada. Para obtener más información, vea «Contextos».

Si un flujo de trabajo llamante pasa una entrada que no se especifica en el flujo llamado, dará un error como resultado.

Ejemplo de on.workflow_call.inputs

on:
  workflow_call:
    inputs:
      username:
        description: 'A username passed from the caller workflow'
        default: 'john-doe'
        required: false
        type: string

jobs:
  print-username:
    runs-on: ubuntu-latest

    steps:
      - name: Print the input name to STDOUT
        run: echo The username is ${{ inputs.username }}

Para obtener más información, vea «Reutilización de flujos de trabajo».

on.workflow_call.inputs.<input_id>.type

Obligatorio si se define la entrada para la palabra clave on.workflow_call. El valor de este parámetro es una secuencia que especifica el tipo de datos de la entrada. Debe ser uno de los siguientes: boolean, number o string.

on.workflow_call.outputs

Un mapa de salidas para un flujo de trabajo llamado. Las salidas de flujo de trabajo llamadas se encuentran disponibles en todos los jobs en línea descendente en el flujo de trabajo llamante. Cada salida tiene un identificador, un valor description, opcional y un valor value.. value se debe establecer en el valor de una salida de un trabajo dentro del flujo de trabajo llamado.

En el ejemplo siguiente, se definen dos salidas para este flujo de trabajo reutilizable: workflow_output1 y workflow_output2. Se asignan a las salidas job_output1 y job_output2, las dos de un trabajo denominado my_job.

Ejemplo de on.workflow_call.outputs

on:
  workflow_call:
    # Map the workflow outputs to job outputs
    outputs:
      workflow_output1:
        description: "The first job output"
        value: ${{ jobs.my_job.outputs.job_output1 }}
      workflow_output2:
        description: "The second job output"
        value: ${{ jobs.my_job.outputs.job_output2 }}

Para obtener información sobre cómo hacer referencia a una salida de trabajo, vea jobs.<job_id>.outputs. Para obtener más información, vea «Reutilización de flujos de trabajo».

on.workflow_call.secrets

Un mapa de los secretos que pueden utilizarse en el flujo de trabajo llamado.

Dentro del flujo de trabajo llamado, puede usar el contexto secrets para hacer referencia a un secreto.

Si un flujo de trabajo llamante pasa un secreto que no se especifica en el flujo de trabajo llamado, esto da un error como resultado.

Ejemplo de on.workflow_call.secrets

on:
  workflow_call:
    secrets:
      access-token:
        description: 'A token passed from the caller workflow'
        required: false

jobs:

  pass-secret-to-action:
    runs-on: ubuntu-latest
    steps:
    # passing the secret to an action
      - name: Pass the received secret to an action
        uses: ./.github/actions/my-action
        with:
          token: ${{ secrets.access-token }}

  # passing the secret to a nested reusable workflow
  pass-secret-to-workflow:
    uses: ./.github/workflows/my-workflow
    secrets:
       token: ${{ secrets.access-token }}

on.workflow_call.secrets.<secret_id>

Un identificador de secuencia para asociar con el secreto.

on.workflow_call.secrets.<secret_id>.required

Un booleano que especifica si el secreto debe suministrarse.

on.workflow_run.<branches|branches-ignore>

Cuando utilice el evento workflow_run, puede especificar qué ramas debe ejecutar el flujo de trabajo activador para que se active tu flujo.

Los filtros branches y branches-ignore aceptan patrones globales que usan caracteres como *, **, +, ? y !, entre otros, para que coincidan con más de un nombre de rama. Si un nombre contiene cualquiera de estos caracteres y quiere una coincidencia literal, necesita escapar a cada uno de estos caracteres especiales con \. Para obtener más información sobre los patrones globales, consulte la "Hoja de referencia rápida de patrones de filtro".

Por ejemplo, un flujo de trabajo con el siguiente activador solo se ejecutará cuando el flujo de trabajo Build se ejecute en una rama cuyo nombre empiece por releases/:

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches:
      - 'releases/**'

Un flujo de trabajo con el siguiente activador solo se ejecutará cuando el flujo de trabajo Build se ejecute en una rama cuyo nombre empiece por canary:

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches-ignore:
      - "canary"

No puede usar los filtros branches y branches-ignore para el mismo evento de un flujo de trabajo. Si quiere tanto incluir como excluir patrones de rama para un solo evento, utilice el filtro branches junto con el carácter ! para indicar qué ramas deberían excluirse.

El orden en que defines los patrones importa.

• El tener una coincidencia de patrón negativo (con prefijo !) después de una coincidencia positiva hará que se excluya la rama.
• El tener un patrón de coincidencia positivo después de una coincidencia negativa hará que se incluya la rama nuevamente.

Por ejemplo, un flujo de trabajo con el siguiente activador se ejecutará cuando el flujo de trabajo Build se ejecute en una cuyo nombre sea releases/10 o releases/beta/mona, pero no releases/10-alpha, releases/beta/3-alpha ni main.

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

on.workflow_dispatch

Cuando se usa el evento workflow_dispatch, puede especificar opcionalmente entradas que se pasan al flujo de trabajo.

on.workflow_dispatch.inputs

El flujo de trabajo desencadenado recibe las entradas en el contexto inputs. Para más información, vea "Contextos".

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning'
        type: choice
        options:
        - info
        - warning
        - debug
      print_tags:
        description: 'True to print to STDOUT'
        required: true
        type: boolean
      tags:
        description: 'Test scenario tags'
        required: true
        type: string
      environment:
        description: 'Environment to run tests against'
        type: environment
        required: true

jobs:
  print-tag:
    runs-on: ubuntu-latest
    if:  ${{ inputs.print_tags }} 
    steps:
      - name: Print the input tag to STDOUT
        run: echo  The tags are ${{ inputs.tags }} 

Ejemplo de on.workflow_dispatch.inputs

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning'
        type: choice
        options:
          - info
          - warning
          - debug
      print_tags:
        description: 'True to print to STDOUT'
        required: true
        type: boolean
      tags:
        description: 'Test scenario tags'
        required: true
        type: string
      environment:
        description: 'Environment to run tests against'
        type: environment
        required: true

jobs:
  print-tag:
    runs-on: ubuntu-latest
    if:  ${{ inputs.print_tags }} 
    steps:
      - name: Print the input tag to STDOUT
        run: echo  The tags are ${{ inputs.tags }} 

on.workflow_dispatch.inputs.<input_id>.required

Valor booleano que especifica si la entrada debe suministrarse.

on.workflow_dispatch.inputs.<input_id>.type

El valor de este parámetro es una secuencia que especifica el tipo de datos de la entrada. Debe ser uno de los siguientes: boolean, choice, environment o string.

permissions

Puede usar permissions para modificar los permisos predeterminados concedidos a GITHUB_TOKEN si se agrega o elimina el acceso según sea necesario, de forma que solo se permita el acceso mínimo necesario. Para obtener más información, vea «Automatic token authentication».

Puede utilizar permissions ya sea como una clave de nivel superior, para aplicarlos a todos los trabajos en el flujo de trabajo, o en los trabajos específicos. Cuando agrega la clave permissions en un trabajo específico, todas las acciones y comandos de ejecución dentro de este que utilicen GITHUB_TOKEN obtendrán los derechos de acceso que especifique. Para más información, vea jobs.<job_id>.permissions.

Alcances y valores de acceso disponibles:

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  id-token: read|write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pages: read|write|none
  pull-requests: read|write|none
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

Si especifica el acceso para cualquiera de estos ámbitos, todos los que no se especifiquen se establecen en none.

Puedes utilizar la siguiente sintaxis para definir el acceso de lectura o escritura para todos los alcances disponibles:

permissions: read-all|write-all

Puedes utilizar la siguiente sintaxis para inhabilitar los permisos para todos los alcances disponibles:

permissions: {}
``` Puede usar la clave `permissions` a fin de agregar y quitar permisos de lectura para repositorios bifurcados, pero normalmente no se puede conceder acceso de escritura. La excepción a este comportamiento es cuando un usuario administrador ha seleccionado la opción **Enviar tokens a flujos de trabajo desde solicitudes de incorporación de cambios** en la configuración de GitHub Actions. Para obtener más información, vea «[AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-private-repository-forks)».

### Ejemplo: Asignar permisos a un GITHUB_TOKEN

En este ejemplo se muestran los permisos que se están configurando para `GITHUB_TOKEN` que aplicará a todos los trabajos en el flujo de trabajo. Se otorga acceso de lectura a todos los permisos.

```yaml
name: "My workflow"

on: [ push ]

permissions: read-all

jobs:
  ...

env

Objeto map de variables de entorno disponibles para los pasos de todos los trabajos del flujo de trabajo. También puedes configurar variables que solo estén disponibles para los pasos en un solo trabajo o en un solo paso. Para más información, vea jobs.<job_id>.env y jobs.<job_id>.steps[*].env.

Las variables del mapa env no se pueden definir en relación a otras variables del mapa.

Cuando se define más de una variable de entorno con el mismo nombre, GitHub utiliza la más específica. Por ejemplo, una variable de entorno definida en un paso anulará aquellas variables de entorno de los trabajos y flujos de trabajo con el mismo nombre, mientras ejecuta el paso. Una variable de entorno definida para un trabajo anulará aquella de un flujo de trabajo si tienen el mismo nombre, mientras se ejecuta el trabajo.

Ejemplo de env

env:
  SERVER: production

defaults

Use defaults para crear un map de configuración predeterminada que se aplicará a todos los trabajos en el flujo de trabajo. También puedes configurar los ajustes predeterminados que solo estén disponibles para un job. Para obtener más información, vea jobs.<job_id>.defaults.

Cuando se define más de una configuración predeterminada con el mismo nombre, GitHub utiliza la configuración predeterminada más específica. Por ejemplo, una configuración predeterminada definida en un job invalidará a aquella que tenga el mismo nombre definido en el flujo de trabajo.

defaults.run

Puedes usar defaults.run para proporcionar las opciones shell y working-directory predeterminadas para todos los pasos de run de un flujo de trabajo. También puedes establecer opciones predeterminadas para run que solo están disponibles para un trabajo. Para más información, vea jobs.<job_id>.defaults.run. No puedes utilizar contextos o expresiones en esta palabra clave.

Cuando se define más de una configuración predeterminada con el mismo nombre, GitHub utiliza la configuración predeterminada más específica. Por ejemplo, una configuración predeterminada definida en un job invalidará a aquella que tenga el mismo nombre definido en el flujo de trabajo.

Ejemplo: Configurar el directorio de trabajo y shell predeterminados

defaults:
  run:
    shell: bash
    working-directory: scripts

concurrency

Utilice concurrency para asegurarse de que solo se ejecute al mismo tiempo un trabajo o flujo de trabajo que use el mismo grupo de concurrencia. Un grupo de concurrencia puede ser cualquier secuencia o expresión. La expresión solo puede usar el contexto github. Para más información sobre las expresiones, vea "Expresiones".

También puede especificar concurrency en el nivel de trabajo. Para más información, vea jobs.<job_id>.concurrency.

Cuando un trabajo o flujo de trabajo concurrente se pone en cola, si otro trabajo o flujo de trabajo que utilicen el mismo grupo de simultaneidad en el repositorio se encuentra en curso, el trabajo o flujo de trabajo en cola se mostrará como pending. Cualquier job o flujo de trabajo pendientes anteriores en el grupo de concurrencia se cancelarán. Para cancelar también cualquier trabajo o flujo de trabajo actualmente en ejecución en el mismo grupo de simultaneidad, especifica cancel-in-progress: true.

Ejemplos: Utilizando la concurrencia y el comportamiento predeterminado

concurrency: staging_environment

concurrency: ci-${{ github.ref }}

Ejemplo: Utilizar la concurrencia para cancelar cualquier job o ejecución en curso

concurrency:
  group: ${{ github.ref }}
  cancel-in-progress: true

Ejemplo: Utilizar un valor para segunda opción

Si compilas el nombre de grupo con una propiedad que solo se defina para eventos específicos, puedes utilizar un valor de segunda opción. Por ejemplo, github.head_ref solo se define en eventos pull_request. Si tu flujo de trabajo responde a otros eventos además de los eventos pull_request, necesitarás proporcionar una segunda opción para evitar un error de sintaxis. El siguiente grupo de simultaneidad cancela los trabajos en curso o solo se ejecuta en eventos pull_request; si github.head_ref no está definido, el grupo de simultaneidad revertirá al identificador de ejecución, que se garantiza que es único y definido para la ejecución.

concurrency:
  group: ${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

Ejemplo: Cancelar únicamente los jobs o ejecuciones en curso para el flujo de trabajo actual

Si tienes flujos de trabajo múltiples en el mismo repositorio, los nombres del grupo de concurrencia deben ser únicos en todos los flujos de trabajo para evitar que se cancelen jobs o ejecuciones en curso desde otros flujos de trabajo. De otra forma, cualquier job pendiente o previamente en curso se cancelará sin importar el flujo de trabajo.

Para cancelar solo las ejecuciones en curso del mismo flujo de trabajo, puedes usar la propiedad github.workflow para compilar el grupo de simultaneidad:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs

Una ejecución de flujo de trabajo se compone de uno o varios jobs, que se ejecutan en paralelo de forma predeterminada. Para ejecutar trabajos de manera secuencial, puede definir dependencias en otros trabajos mediante la palabra clave jobs.<job_id>.needs.

Cada trabajo se ejecuta en un entorno de ejecutor especificado por runs-on.

Puedes ejecutar una cantidad ilimitada de trabajos siempre que estés dentro de los límites de uso del flujo de trabajo. Para más información, vea "Límites de uso, facturación y administración" para ejecutores hospedados en GitHub y "Acerca de los ejecutores autohospedados" para los límites de uso del ejecutor autohospedado.

Si necesitas encontrar el identificador único de un job que se ejecuta en una ejecución de flujo de trabajo, puedes utilizar la API de GitHub. Para obtener más información, vea «Acciones».

jobs.<job_id>

Usa jobs.<job_id> para asignar un identificador único al trabajo. La clave job_id es una cadena y su valor es un mapa de los datos de configuración del trabajo. Debes reemplazar <job_id> por una cadena que sea única para el objeto jobs. <job_id> debe empezar con una letra o _, y solo puede contener caracteres alfanuméricos, - o _.

Ejemplo: Crear jobs

En este ejemplo, se han creado dos trabajos y sus valores job_id son my_first_job y my_second_job.

jobs:
  my_first_job:
    name: My first job
  my_second_job:
    name: My second job

jobs.<job_id>.name

Usa jobs.<job_id>.name a fin de establecer un nombre para el trabajo, que se muestra en la UI de GitHub.

jobs.<job_id>.permissions

Para un trabajo concreto, puede usar jobs.<job_id>.permissions para modificar los permisos predeterminados concedidos a GITHUB_TOKEN si se agrega o elimina el acceso según sea necesario, de forma que solo se permita el acceso mínimo necesario. Para obtener más información, vea «Automatic token authentication».

Al especificar el permiso dentro de una definición de trabajo, puede configurar un conjunto diferente de permisos para el GITHUB_TOKEN de cada trabajo, si es necesario. Como alternativa, puedes especificar los permisos para todos los jobs en el flujo de trabajo. Para obtener información sobre cómo definir permisos en el nivel de flujo de trabajo, vea permissions.

Alcances y valores de acceso disponibles:

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  id-token: read|write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pages: read|write|none
  pull-requests: read|write|none
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

Si especifica el acceso para cualquiera de estos ámbitos, todos los que no se especifiquen se establecen en none.

Puedes utilizar la siguiente sintaxis para definir el acceso de lectura o escritura para todos los alcances disponibles:

permissions: read-all|write-all

Puedes utilizar la siguiente sintaxis para inhabilitar los permisos para todos los alcances disponibles:

permissions: {}
``` Puede usar la clave `permissions` a fin de agregar y quitar permisos de lectura para repositorios bifurcados, pero normalmente no se puede conceder acceso de escritura. La excepción a este comportamiento es cuando un usuario administrador ha seleccionado la opción **Enviar tokens a flujos de trabajo desde solicitudes de incorporación de cambios** en la configuración de GitHub Actions. Para obtener más información, vea «[AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-private-repository-forks)».

#### Ejemplo: Configurar los permisos para un job específico

En este ejemplo se muestran los permisos establecidos para `GITHUB_TOKEN` que solo se aplicarán al trabajo denominado `stale`. Se concede acceso de escritura a los ámbitos `issues` y `pull-requests`. El resto de los alcances no tendrán acceso.

```yaml
jobs:
  stale:
    runs-on: ubuntu-latest

    permissions:
      issues: write
      pull-requests: write

    steps:
      - uses: actions/stale@v5

jobs.<job_id>.needs

Use jobs.<job_id>.needs para identificar los trabajos que se deben completar correctamente antes de que se ejecute este trabajo. Puede ser una cadena o matriz de cadenas. Si un job falla, se saltarán todos los jobs que lo necesiten a menos de que éstos utilicen una expresión condicional que ocasione que el job continúe. Si una ejecución contiene una serie de trabajos que se necesitan entre sí, se aplica un error a todos los trabajos de la cadena de dependencias desde el punto de error en adelante.

Ejemplo: Requerir jobs dependientes exitosos

jobs:
  job1:
  job2:
    needs: job1
  job3:
    needs: [job1, job2]

En este ejemplo, job1 se debe completar correctamente antes de que comience job2 y job3 espera a que se completen job1 y job2.

En este ejemplo, los trabajos se ejecutan de manera secuencial:

1. job1
2. job2
3. job3

Ejemplo: No requerir jobs dependientes exitosos

jobs:
  job1:
  job2:
    needs: job1
  job3:
    if: ${{ always() }}
    needs: [job1, job2]

En este ejemplo, job3 usa la expresión condicional always() para que siempre se ejecute después de que se hayan completado job1 y job2, independientemente de si se han realizado correctamente. Para más información, vea "Expresiones".

jobs.<job_id>.if

Puede usar el condicional jobs.<job_id>.if para impedir que se ejecute una tarea si no se cumple una condición. Puedes usar cualquier contexto y expresión admitidos para crear un condicional. Para obtener más información sobre qué contextos se admiten en esta clave, consulta "Disponibilidad de contexto".

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, consulta "Expresiones".

Ejemplo: Solo ejecutar un job para un repositorio específico

En este ejemplo se usa if para controlar cuándo se puede ejecutar el trabajo production-deploy. Solo se ejecutará si el repositorio se denomina octo-repo-prod y está dentro de la organización octo-org. De lo contrario, el trabajo se marcará como omitido.

name: example-workflow
on: [push]
jobs:
  production-deploy:
    if: github.repository == 'octo-org/octo-repo-prod'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '14'
      - run: npm install -g bats

jobs.<job_id>.runs-on

Use jobs.<job_id>.runs-on para definir el tipo de máquina en la que se ejecutará el trabajo.

: la máquina de destino puede ser un ejecutor hospedado por GitHub, ejecutor más grande o un ejecutor autohospedado. : puede dirigirse a los ejecutores en función de las etiquetas que se les han asignado, su pertenencia a grupos o una combinación de ambos.

• Puedes proporcionar runs-on como una sola cadena o como una matriz de cadenas.
• Si especificas una matriz de cadenas, el flujo de trabajo se ejecutará en cualquier ejecutor que coincida con todos los valores runs-on especificados.
• Si quiere ejecutar el flujo de trabajo en varias máquinas, use jobs.<job_id>.strategy.

Selección de ejecutores hospedados en GitHub

Si usas un ejecutor hospedado en GitHub, cada trabajo se ejecuta en una nueva instancia de una imagen de ejecutor especificada por runs-on.

Los tipos de ejecutores alojados GitHub disponibles son:

Ejemplo: Especificación de un sistema operativo

runs-on: ubuntu-latest

Para obtener más información, vea «Acerca de los ejecutores hospedados en GitHub».

Selección de ejecutores autohospedados

A fin de especificar un ejecutor autohospedado para el trabajo, configure runs-on en el archivo de flujo de trabajo con las etiquetas de ejecutor autohospedado.

Todos los ejecutores autohospedados tienen la etiqueta self-hosted. El utilizar únicamente esta etiqueta seleccionará cualquier ejecutor auto-hospedado. Para seleccionar los ejecutores que cumplen con determinados criterios, como el sistema operativo o la arquitectura, se recomienda proporcionar una serie de etiquetas que comience con self-hosted (debe estar en primer lugar) y que luego incluya etiquetas adicionales según sea necesario. Cuando especifiques un arreglo de etiquetas, los jobs se pondrán en cola cuando se trate de ejecutores que tengan todas las etiquetas que especificas.

Aunque la etiqueta self-hosted no es obligatoria, se recomienda encarecidamente especificarla cuando se usen ejecutores autohospedados, para garantizar que el trabajo no especifique un ejecutor hospedado en GitHub futuro o actual por accidente.

Ejemplo: Uso de etiquetas para la selección del ejecutor

runs-on: [self-hosted, linux]

Para obtener más información, vea «Acerca de los ejecutores autohospedados» y «Uso de ejecutores autohospedados en un flujo de trabajo».

Elección de ejecutores en un grupo

Puedes usar runs-on para dirigirte a grupos de ejecutores, de modo que el trabajo se ejecute en cualquier ejecutor que sea miembro de ese grupo. Para un control más granular, también puedes combinar grupos de ejecutores con etiquetas.

Los grupos de ejecutores solo pueden tener ejecutor más grande o ejecutores autohospedados como miembros.

Ejemplo: Uso de grupos para controlar dónde se ejecutan los trabajos

En este ejemplo, se han agregado ejecutores de Ubuntu a un grupo denominado ubuntu-runners. La clave runs-on envía el trabajo a cualquier ejecutor disponible del grupo ubuntu-runners:

name: learn-github-actions
on: [push]
jobs:
  check-bats-version:
    runs-on: 
      group: ubuntu-runners
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '14'
      - run: npm install -g bats
      - run: bats -v

Ejemplo: Combinación de grupos y etiquetas

Al combinar grupos y etiquetas, el ejecutor debe cumplir ambos requisitos para poder ejecutar el trabajo.

En este ejemplo, un grupo de ejecutores denominado ubuntu-runners se rellena con ejecutores de Ubuntu, a los que también se ha asignado la etiqueta ubuntu-20.04-16core. La clave runs-on combina group y labels para que el trabajo se enrute a cualquier ejecutor disponible dentro del grupo que también tenga una etiqueta coincidente:

name: learn-github-actions
on: [push]
jobs:
  check-bats-version:
    runs-on:
      group: ubuntu-runners
      labels: ubuntu-20.04-16core
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '14'
      - run: npm install -g bats
      - run: bats -v

jobs.<job_id>.environment

Use jobs.<job_id>.environment para definir el entorno al que hace referencia el trabajo. Todas las reglas de protección del ambiente deben pasar antes de que un job que referencie dicho ambiente se envie a un ejecutor. Para más información, vea "Uso de entornos para la implementación".

Puede proporcionar el entorno como solo el entorno name, o bien como un objeto de entorno con name y url. La dirección URL se asigna a environment_url en la API de implementaciones. Para más información sobre la API de implementaciones, vea "Implementaciones".

Ejemplo: Utilizar un solo nombre de ambiente

environment: staging_environment

Ejemplo: Uso de un nombre y una URL de entorno

environment:
  name: production_environment
  url: https://github.com

La URL puede ser una expresión y puede utilizar cualquier contexto con excepción del contexto secrets. Para más información sobre las expresiones, vea "Expresiones".

Ejemplo: Uso de la salida como dirección URL

environment:
  name: production_environment
  url: ${{ steps.step_id.outputs.url_output }}

jobs.<job_id>.concurrency

Use jobs.<job_id>.concurrency para asegurarse de que solo se ejecute al mismo tiempo un trabajo o flujo de trabajo que use el mismo grupo de concurrencia. Un grupo de concurrencia puede ser cualquier secuencia o expresión. La expresión puede usar cualquier contexto excepto secrets. Para más información sobre las expresiones, vea "Expresiones".

También puede especificar concurrency en el nivel de flujo de trabajo. Para más información, vea concurrency.

Cuando un trabajo o flujo de trabajo concurrente se pone en cola, si otro trabajo o flujo de trabajo que utilicen el mismo grupo de simultaneidad en el repositorio se encuentra en curso, el trabajo o flujo de trabajo en cola se mostrará como pending. Cualquier job o flujo de trabajo pendientes anteriores en el grupo de concurrencia se cancelarán. Para cancelar también cualquier trabajo o flujo de trabajo actualmente en ejecución en el mismo grupo de simultaneidad, especifica cancel-in-progress: true.

Ejemplos: Utilizando la concurrencia y el comportamiento predeterminado

concurrency: staging_environment

concurrency: ci-${{ github.ref }}

Ejemplo: Utilizar la concurrencia para cancelar cualquier job o ejecución en curso

concurrency:
  group: ${{ github.ref }}
  cancel-in-progress: true

Ejemplo: Utilizar un valor para segunda opción

Si compilas el nombre de grupo con una propiedad que solo se defina para eventos específicos, puedes utilizar un valor de segunda opción. Por ejemplo, github.head_ref solo se define en eventos pull_request. Si tu flujo de trabajo responde a otros eventos además de los eventos pull_request, necesitarás proporcionar una segunda opción para evitar un error de sintaxis. El siguiente grupo de simultaneidad cancela los trabajos en curso o solo se ejecuta en eventos pull_request; si github.head_ref no está definido, el grupo de simultaneidad revertirá al identificador de ejecución, que se garantiza que es único y definido para la ejecución.

concurrency:
  group: ${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

Ejemplo: Cancelar únicamente los jobs o ejecuciones en curso para el flujo de trabajo actual

Si tienes flujos de trabajo múltiples en el mismo repositorio, los nombres del grupo de concurrencia deben ser únicos en todos los flujos de trabajo para evitar que se cancelen jobs o ejecuciones en curso desde otros flujos de trabajo. De otra forma, cualquier job pendiente o previamente en curso se cancelará sin importar el flujo de trabajo.

Para cancelar solo las ejecuciones en curso del mismo flujo de trabajo, puedes usar la propiedad github.workflow para compilar el grupo de simultaneidad:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs.<job_id>.outputs

Puede usar jobs.<job_id>.outputs para crear un objeto map de salidas para un trabajo. Las salidas de un job se encuentran disponibles para todos los jobs descendentes que dependan de este job. Para más información sobre cómo definir dependencias de trabajo, vea jobs.<job_id>.needs.

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.

Las salidas de un trabajo que incluyen expresiones se evalúan en el ejecutor al final de cada trabajo. Las salidas que contienen secretos se redactan en el ejecutor y no se envían a GitHub Actions.

Para usar salidas de trabajo en un trabajo dependiente, puede utilizar el contexto needs. Para obtener más información, vea «Contextos».

Ejemplo: definir salidas para un job

jobs:
  job1:
    runs-on: ubuntu-latest
    # Map a step output to a job output
    outputs:
      output1: ${{ steps.step1.outputs.test }}
      output2: ${{ steps.step2.outputs.test }}
    steps:
      - id: step1
        run: echo "test=hello" >> "$GITHUB_OUTPUT"
      - id: step2
        run: echo "test=world" >> "$GITHUB_OUTPUT"
  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - env:
          OUTPUT1: ${{needs.job1.outputs.output1}}
          OUTPUT2: ${{needs.job1.outputs.output2}}
        run: echo "$OUTPUT1 $OUTPUT2"

jobs.<job_id>.env

Objeto map de las variables disponibles para todos los pasos del trabajo. También puedes establecer las variables para todo el flujo de trabajo o para un paso en particular. Para más información, vea env y jobs.<job_id>.steps[*].env.

Cuando se define más de una variable de entorno con el mismo nombre, GitHub utiliza la más específica. Por ejemplo, una variable de entorno definida en un paso anulará aquellas variables de entorno de los trabajos y flujos de trabajo con el mismo nombre, mientras ejecuta el paso. Una variable de entorno definida para un trabajo anulará aquella de un flujo de trabajo si tienen el mismo nombre, mientras se ejecuta el trabajo.

Ejemplo de jobs.<job_id>.env

jobs:
  job1:
    env:
      FIRST_NAME: Mona

jobs.<job_id>.defaults

Use jobs.<job_id>.defaults para crear un elemento map de configuración predeterminada que se aplicará a todos los pasos del trabajo. También puedes configurar ajustes predeterminados para todo el flujo de trabajo. Para obtener más información, vea defaults.

Cuando se define más de una configuración predeterminada con el mismo nombre, GitHub utiliza la configuración predeterminada más específica. Por ejemplo, una configuración predeterminada definida en un job invalidará a aquella que tenga el mismo nombre definido en el flujo de trabajo.

jobs.<job_id>.defaults.run

Use jobs.<job_id>.defaults.run para proporcionar el valor predeterminado de shell y working-directory para todos los pasos run del trabajo. No se permiten las expresiones ni contexto en esta sección.

Puede proporcionar las opciones predeterminadas de shell y working-directory para todos los pasos run de un trabajo. También puede establecer la configuración predeterminada de run para todo el flujo de trabajo. Para más información, vea jobs.defaults.run. No puedes utilizar contextos o expresiones en esta palabra clave.

Cuando se define más de una configuración predeterminada con el mismo nombre, GitHub utiliza la configuración predeterminada más específica. Por ejemplo, una configuración predeterminada definida en un job invalidará a aquella que tenga el mismo nombre definido en el flujo de trabajo.

Ejemplo: Establecimiento de las opciones predeterminadas de los pasos run para un trabajo

jobs:
  job1:
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
        working-directory: scripts

jobs.<job_id>.steps

Un trabajo contiene una secuencia de tareas denominada steps. Los pasos pueden ejecutar comandos, tareas de configuración o una acción en tu repositorio, un repositorio público o una acción publicada en un registro de Docker. No todos los pasos ejecutan acciones, pero todas las acciones se ejecutan como un paso. Cada paso se ejecuta en su propio proceso en el ambiente ejecutor y tiene acceso al espacio de trabajo y al sistema de archivos. Ya que los pasos se ejecutan en su propio proceso, los cambios a las variables de ambiente no se preservan entre pasos. GitHub proporciona pasos integrados para configurar y completar un job.

Puedes ejecutar un número de pasos ilimitado siempre que estés dentro de los límites de uso del flujo de trabajo. Para más información, vea "Límites de uso, facturación y administración" para ejecutores hospedados en GitHub y "Acerca de los ejecutores autohospedados" para los límites de uso del ejecutor autohospedado.

Ejemplo de jobs.<job_id>.steps

name: Greeting from Mona

on: push

jobs:
  my-job:
    name: My Job
    runs-on: ubuntu-latest
    steps:
      - name: Print a greeting
        env:
          MY_VAR: Hi there! My name is
          FIRST_NAME: Mona
          MIDDLE_NAME: The
          LAST_NAME: Octocat
        run: |
          echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME.

jobs.<job_id>.steps[*].id

Un identificador único para el paso. Puede usar id para hacer referencia al paso en los contextos. Para obtener más información, vea «Contextos».

jobs.<job_id>.steps[*].if

Puede usar el 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. Para obtener más información sobre qué contextos se admiten en esta clave, consulta "Disponibilidad de contexto".

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, consulta "Expresiones".

Ejemplo: Utilizando contextos

Este paso solo se ejecuta cuando el tipo de evento es pull_request y la acción del evento es unassigned.

steps:
 - name: My first step
   if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}
   run: echo This event is a pull request that had an assignee removed.

Ejemplo: Utilizando funciones de verificación de estado

El objeto my backup step solo se ejecuta cuando se produce un error en el paso anterior de un trabajo. 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

Ejemplo: Utilizar secretos

No se puede hacer referencia a los secretos directamente en las condicionales if:. En vez de esto, considera configurar secretos como variables de ambiente a nivel de jobs y luego referencia dichas variables para ejecutar pasos de forma condicional en el job.

Si no se ha establecido un secreto, el valor devuelto de una expresión que hace referencia al secreto (como ${{ secrets.SuperSecret }} en el ejemplo) será una cadena vacía.

name: Run a step if a secret has been set
on: push
jobs:
  my-jobname:
    runs-on: ubuntu-latest
    env:
      super_secret: ${{ secrets.SuperSecret }}
    steps:
      - if: ${{ env.super_secret != '' }}
        run: echo 'This step will only run if the secret has a value set.'
      - if: ${{ env.super_secret == '' }}
        run: echo 'This step will only run if the secret does not have a value set.'

Para obtener más información, vea «Contextos» y «Secretos cifrados».

jobs.<job_id>.steps[*].name

Un nombre para que tu paso se muestre en GitHub.

jobs.<job_id>.steps[*].uses

Selecciona una acción a ejecutar como parte de un paso en tu 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 encarecidamente que incluyas la versión de la acción que estás utilizando. Para ello, especifica una referencia de Git, SHA o una etiqueta de 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.
• Si la acción publica etiquetas de versiones principales, debes esperar recibir correcciones críticas y parches de seguridad a la vez que se conserva la compatibilidad. Ten en cuenta que este comportamiento queda a discreción del autor de la acción.
• 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.

Las acciones son archivos de JavaScript o contenedores de Docker. Si la acción que estás usando es un contenedor de Docker, debes ejecutar el job en un ambiente Linux. Para obtener información, vea runs-on.

Ejemplo: Utilizando acciones versionadas

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

Ejemplo: Utilizando una acción pública

{owner}/{repo}@{ref}

Puedes especificar una rama, ref, o SHA en un repositorio público de GitHub.

jobs:
  my_first_job:
    steps:
      - name: My first step
        # Uses the default branch of a public repository
        uses: actions/heroku@main
      - name: My second step
        # Uses a specific version tag of a public repository
        uses: actions/aws@v2.0.1

Ejemplo: Utilizando una acción pública en un subdirectorio

{owner}/{repo}/{path}@{ref}

Un subdirectorio en un repositorio público de GitHub en una rama, ref o SHA específicos.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/aws/ec2@main

Ejemplo: Utilizando una acción en el mismo repositorio que el flujo de trabajo

./path/to/dir

La ruta al directorio que contiene la acción en el repositorio de tu flujo de trabajo. Debes revisar tu repositorio antes de usar la acción.

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v3
      - name: Use local my-action
        uses: ./.github/actions/my-action

Ejemplo: Utilizando una acción de Docker Hub

docker://{image}:{tag}

Una imagen de Docker publicada en Docker Hub.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://alpine:3.8

Ejemplo: Utilizando el Container registry del GitHub Packages

docker://{host}/{image}:{tag}

Una imagen pública de Docker en los datos GitHub Packages Container registry.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://ghcr.io/OWNER/IMAGE_NAME

Ejemplo: Utilizando una acción del registro público de Docker

docker://{host}/{image}:{tag}

Una imagen de Docker en un registro público. En este ejemplo se usa Google Container Registry en gcr.io.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://gcr.io/cloud-builders/gradle

Ejemplo: Utilizando una acción dentro de un repositorio privado diferente al del flujo de trabajo

Tu flujo de trabajo debe registrar el repositorio privado y referenciar la acción de forma local. Genera un personal access token y agrega el token como un secreto cifrado. Para obtener más información, vea «Workflow syntax for GitHub Actions» y «Secretos cifrados».

Reemplace PERSONAL_ACCESS_TOKEN en el ejemplo por el nombre del secreto.

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v3
        with:
          repository: octocat/my-private-repo
          ref: v1.0
          token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          path: ./.github/actions/my-private-repo
      - name: Run my action
        uses: ./.github/actions/my-private-repo/my-action

jobs.<job_id>.steps[*].run

Ejecuta programas de la línea de comandos usando el shell del sistema operativo. Si no proporciona un valor name, el nombre del paso tendrá como valor predeterminado el texto especificado en el comando run.

Predeterminadamente, los comandos se ejecutan utilizando shells diferentes a los de ingreso. Puedes elegir un shell diferente y personalizar el que utilizaste para ejecutar los comandos. Para más información, vea jobs.<job_id>.steps[*].shell.

Cada palabra clave run representa un nuevo proceso y shell en el entorno del ejecutor. Cuando proporcionas comandos de varias líneas, cada línea se ejecuta en el mismo shell. Por ejemplo:

• Comando de una sola línea:

  - name: Install Dependencies
    run: npm install
  

• Comando de varias líneas:

  - name: Clean install dependencies and build
    run: |
      npm ci
      npm run build
  

Con la palabra clave working-directory, puede especificar el directorio de trabajo desde el que ejecutar el comando.

- name: Clean temp directory
  run: rm -rf *
  working-directory: ./temp

jobs.<job_id>.steps[*].shell

Puede invalidar los valores del shell predeterminado en el sistema operativo del ejecutor mediante la palabra clave shell. Puede usar palabras clave shell integradas, o bien puede definir un conjunto personalizado de opciones de shell. El comando de shell que se ejecuta internamente ejecuta un archivo temporal que contiene los comandos especificados en la palabra clave run.

Ejemplo: Ejecutando un script utilizando bash

steps:
  - name: Display the path
    run: echo $PATH
    shell: bash

Ejemplo: Ejecución de un script con Windows cmd

steps:
  - name: Display the path
    run: echo %PATH%
    shell: cmd

Ejemplo: Ejecutando un script utilizando PowerShell Core

steps:
  - name: Display the path
    run: echo ${env:PATH}
    shell: pwsh

Ejemplo: Utilizar PowerShell Desktop para ejecutar un script

steps:
  - name: Display the path
    run: echo ${env:PATH}
    shell: powershell

Ejemplo: Ejecutando un script de python

steps:
  - name: Display the path
    run: |
      import os
      print(os.environ['PATH'])
    shell: python

Shell personalizado

Puede establecer el valor shell en una cadena de plantilla mediante command […options] {0} [..more_options]. GitHub interpreta la primera palabra delimitada por espacios en blanco de la cadena como el comando e inserta el nombre del archivo para el script temporal en {0}.

Por ejemplo:

steps:
  - name: Display the environment variables and their values
    run: |
      print %ENV
    shell: perl {0}

El comando que se usa, perl en este ejemplo, debe estar instalado en el ejecutor.

Para obtener información sobre el software incluido en los ejecutores hospedados en GitHub, vea "Acerca de los ejecutores hospedados en GitHub".

Códigos de salida y preferencia de acción de error

Para palabras clave shell incorporadas, brindamos los siguientes valores predeterminados accionados por los ejecutadores alojados por GitHub. Deberías usar estos lineamientos al ejecutar scripts de shell.

• bash/sh:

  • Comportamiento con respuesta rápida a errores mediante set -eo pipefail: esta opción se establece cuando shell: bash se especifica de manera explícita. No se aplica de manera predeterminada.
  • Puedes controlar completamente los parámetros del shell al proporcionar una cadena de plantilla a las opciones del shell. Por ejemplo, bash {0}.
  • Los shells tipo sh salen con el código de salida del último comando ejecutado en un script, que también es el comportamiento predeterminado para las acciones. El ejecutor informará el estado del paso como fallido o exitoso según este código de salida.

• powershell/pwsh

  • Comportamiento de falla rápida cuando sea posible. Para el shell integrado de pwsh y powershell, se antepondrá $ErrorActionPreference = 'stop' al contenido del script.
  • Se anexa if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } a los scripts de PowerShell para que los estados de acción reflejen el último código de salida del script.
  • Los usuarios siempre pueden optar por no usar el shell integrado y proporcionar una opción de shell personalizada como pwsh -File {0} o powershell -Command "& '{0}'", según sea necesario.

• cmd

  • No parece haber una manera de optar por completo por un comportamiento de falla rápida que no sea escribir tu script para verificar cada código de error y responder en consecuencia. Debido a que en realidad no podemos proporcionar ese comportamiento por defecto, debes escribir este comportamiento en tu script.
  • cmd.exe saldrá con el nivel de error del último programa que ha ejecutado y devolverá el código de error al ejecutor. Este comportamiento es internamente coherente con el comportamiento predeterminado de sh y pwsh anterior, y es el cmd.exe predeterminado, por lo que este comportamiento permanece intacto.

jobs.<job_id>.steps[*].with

Objeto map de los parámetros de entrada definidos por la acción. Cada parámetro de entrada es un par clave/valor. Los parámetros de entrada se establecen como variables de entorno. La variable utiliza el prefijo INPUT_ se convierte en mayúsculas.

Ejemplo de jobs.<job_id>.steps[*].with

Define los tres parámetros de entrada (first_name, middle_name y last_name) definidos por la acción hello_world. Estas variables de entrada serán accesibles para la acción hello-world como las variables de entorno INPUT_FIRST_NAME, INPUT_MIDDLE_NAME y INPUT_LAST_NAME.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/hello_world@main
        with:
          first_name: Mona
          middle_name: The
          last_name: Octocat

jobs.<job_id>.steps[*].with.args

Objeto string que define las entradas de un contenedor de Docker. GitHub pasa args al valor ENTRYPOINT del contenedor cuando se inicia. Este parámetro no admite un objeto array of strings. Un solo argumento que incluya espacios debe estar entre comillas dobles "".

Ejemplo de jobs.<job_id>.steps[*].with.args

steps:
  - name: Explain why this job ran
    uses: octo-org/action-name@main
    with:
      entrypoint: /bin/echo
      args: The ${{ github.event_name }} event triggered this step.

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, úsela como valor predeterminado para que la acción se documente de forma automática.

jobs.<job_id>.steps[*].with.entrypoint

Invalida ENTRYPOINT de Docker en Dockerfile, o bien lo establece si todavía no se ha especificado uno. A diferencia de la instrucción ENTRYPOINT de Docker que tiene un formato de shell y archivo ejecutable, la palabra clave entrypoint solo acepta una cadena que define el archivo ejecutable que se va a ejecutar.

Ejemplo de jobs.<job_id>.steps[*].with.entrypoint

steps:
  - name: Run a custom command
    uses: octo-org/action-name@main
    with:
      entrypoint: /a/different/executable

La palabra clave entrypoint se debe usar con acciones de contenedor de Docker, pero también se puede utilizar con acciones de JavaScript que no definan ninguna entrada.

jobs.<job_id>.steps[*].env

Establece variables para los pasos a utilizar en el entorno del ejecutor. También puedes establecer las variables para todo el flujo de trabajo o para una tarea. Para más información, vea env y jobs.<job_id>.env.

Cuando se define más de una variable de entorno con el mismo nombre, GitHub utiliza la más específica. Por ejemplo, una variable de entorno definida en un paso anulará aquellas variables de entorno de los trabajos y flujos de trabajo con el mismo nombre, mientras ejecuta el paso. Una variable de entorno definida para un trabajo anulará aquella de un flujo de trabajo si tienen el mismo nombre, mientras se ejecuta el trabajo.

Es posible que las acciones públicas especifiquen las variables esperadas en el archivo README. Si vas a establecer un secreto o un valor confidencial, como una contraseña o un token, debes establecer secretos mediante el contexto secrets. Para obtener más información, vea «Contextos».

Ejemplo de jobs.<job_id>.steps[*].env

steps:
  - name: My first action
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      FIRST_NAME: Mona
      LAST_NAME: Octocat

jobs.<job_id>.steps[*].continue-on-error

Impide que un trabajo falle cuando falla un paso. Establézcalo en true para permitir que un trabajo se supere cuando se produzca un error en este paso.

jobs.<job_id>.steps[*].timeout-minutes

El número máximo de minutos para ejecutar el paso antes de terminar el proceso.

jobs.<job_id>.timeout-minutes

La cantidad máxima de minutos para permitir que un trabajo se ejecute antes que GitHub lo cancele automáticamente. Predeterminado: 360

Si el tiempo de espera excede el límite de tiempo de ejecución del job para el ejecutor, dicho job se cancelará cuando se llegue al límite de tiempo de ejecución. Para obtener más información sobre los límites de tiempo de ejecución de los trabajos, consulte "Límites de uso, facturación y administración" para los ejecutores hospedados en GitHub y "Acerca de los ejecutores autohospedados" para los límites de uso de los ejecutores autohospedados.".

jobs.<job_id>.strategy

Usa jobs.<job_id>.strategy para emplear una estrategia de matriz en los trabajos. Una estrategia de matriz permite usar variables en una definición de trabajo para crear automáticamente varias ejecuciones de trabajos basadas en las combinaciones de las variables. Por ejemplo, puedes usar una estrategia de matriz para probar el código en varias versiones de un lenguaje o en varios sistemas operativos. Para obtener más información, consulta "Uso de una matriz para tus trabajos".

jobs.<job_id>.strategy.matrix

Use jobs.<job_id>.strategy.matrix definir una matriz de diferentes configuraciones de trabajo. En la matriz, define una o más variables seguidas de una matriz de valores. Por ejemplo, la matriz siguiente tiene una variable llamada version con el valor [10, 12, 14] y una variable llamada os con el valor [ubuntu-latest, windows-latest]:

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]

Se ejecutará un trabajo para cada combinación posible de las variables. En este ejemplo, el flujo de trabajo ejecutará seis trabajos, uno por cada combinación de las variables os y version.

De forma predeterminada, GitHub Enterprise Cloud maximizará el número de trabajos ejecutados en paralelo en función de la disponibilidad del ejecutor. El orden de las variables de la matriz determina el orden en el que se crean los trabajos. La primera variable que definas será el primer trabajo que se cree en tu ejecución de flujo de trabajo. Por ejemplo, la matriz anterior creará los trabajos en el orden siguiente:

• {version: 10, os: ubuntu-latest}
• {version: 10, os: windows-latest}
• {version: 12, os: ubuntu-latest}
• {version: 12, os: windows-latest}
• {version: 14, os: ubuntu-latest}
• {version: 14, os: windows-latest}

Una matriz puede generar un máximo de 256 trabajos por ejecución de flujo de trabajo. Este límite se aplica tanto a los ejecutores autohospedados como a los hospedados por GitHub Enterprise Cloud.

Las variables que defines se convierten en propiedades en el contexto de matrix y puedes hacer referencia a la propiedad en otras áreas del archivo de flujo de trabajo. En este ejemplo, puedes usar matrix.version y matrix.os para acceder al valor actual de version y os que el trabajo utiliza. Para obtener más información, vea «Contextos».

Ejemplo: Uso de una matriz de una sola dimensión

Puedes especificar una variable para crear una matriz de una sola dimensión.

Por ejemplo, el flujo de trabajo siguiente define la variable version con los valores [10, 12, 14]. El flujo de trabajo ejecutará tres trabajos, uno para cada valor de la variable. Cada trabajo tendrá acceso al valor version mediante el contexto matrix.version y pasará el valor como node-version a la acción actions/setup-node.

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.version }}

Ejemplo: Uso de una matriz de varias dimensiones

Puedes especificar varias variables para crear una matriz multidimensional. Se ejecutará un trabajo para cada combinación posible de las variables.

Por ejemplo, el flujo de trabajo siguiente especifica dos variables:

• Dos sistemas operativos especificados en la variable os
• Tres versiones de Node.js especificadas en la variable version

El flujo de trabajo ejecutará seis trabajos, uno para cada combinación de las variables os y version. Cada trabajo establecerá el valor runs-on en el valor os actual y pasará el valor version actual a la acción actions/setup-node.

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [ubuntu-22.04, ubuntu-20.04]
        version: [10, 12, 14]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.version }}

Ejemplo: Uso de contextos para crear matrices

Puedes usar contextos para crear matrices. Para obtener más información sobre los contextos, vea "Contextos".

Por ejemplo, el flujo de trabajo siguiente desencadena el evento repository_dispatch y usa información de la carga del evento para compilar la matriz. Cuando se crea un evento de distribución de repositorio con una carga como la siguiente, la variable de matriz version tendrá un valor de [12, 14, 16]. Para obtener más información sobre el evento repository_dispatch, consulta «Eventos que desencadenan flujos de trabajo».

{
  "event_type": "test",
  "client_payload": {
    "versions": [12, 14, 16]
  }
}

on:
  repository_dispatch:
    types:
      - test
 
jobs:
  example_matrix:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        version: ${{ github.event.client_payload.versions }}
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.version }}

jobs.<job_id>.strategy.matrix.include

Usa jobs.<job_id>.strategy.matrix.include para expandir las configuraciones de matriz existentes o para agregar nuevas configuraciones. El valor de include es una lista de objetos.

Para cada objeto de la lista include, los pares clave:valor del objeto se agregarán a cada una de las combinaciones de matriz si ninguno de los pares clave:valor sobrescribe ninguno de los valores de matriz originales. Si el objeto no se puede agregar a ninguna de las combinaciones de matriz, se creará una nueva combinación de matriz. Ten en cuenta que los valores originales de matriz no se sobrescribirán, mientras que los valores agregados de matriz sí se pueden sobrescribir.

Por ejemplo, esta matriz:

strategy:
  matrix:
    fruit: [apple, pear]
    animal: [cat, dog]
    include:
      - color: green
      - color: pink
        animal: cat
      - fruit: apple
        shape: circle
      - fruit: banana
      - fruit: banana
        animal: cat

dará como resultado seis trabajos con las siguientes combinaciones de matriz:

• {fruit: apple, animal: cat, color: pink, shape: circle}
• {fruit: apple, animal: dog, color: green, shape: circle}
• {fruit: pear, animal: cat, color: pink}
• {fruit: pear, animal: dog, color: green}
• {fruit: banana}
• {fruit: banana, animal: cat}

siguiendo esta lógica:

• {color: green} se agrega a todas las combinaciones de matriz original, porque se puede agregar sin sobrescribir ninguna parte de las combinaciones originales.
• {color: pink, animal: cat} agrega color:pink solo a las combinaciones de matriz originales que incluyen animal: cat. Esto sobrescribe el color: green que ha sido agregado por la entrada anterior include.
• {fruit: apple, shape: circle} agrega shape: circle solo a las combinaciones de matriz originales que incluyen fruit: apple.
• {fruit: banana} no se puede agregar a ninguna combinación de matriz original sin sobrescribir un valor, por lo que se agrega como una combinación de matriz adicional.
• {fruit: banana, animal: cat} no se puede agregar a ninguna combinación de matriz original sin sobrescribir un valor, por lo que se agrega como una combinación de matriz adicional. No se agrega a la combinación de matriz {fruit: banana} porque esa combinación no era una de las combinaciones de matriz original.

Ejemplo: Expansión de configuraciones

Por ejemplo, el siguiente flujo de trabajo ejecutará seis trabajos, uno para cada combinación de os y node. Cuando se ejecute el trabajo para el valor de os de windows-latest y el valor de node de 16, se incluirá en el trabajo una variable adicional denominada npm con el valor de 6.

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [windows-latest, ubuntu-latest]
        node: [12, 14, 16]
        include:
          - os: windows-latest
            node: 16
            npm: 6
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node }}
      - if: ${{ matrix.npm }}
        run: npm install -g npm@${{ matrix.npm }}
      - run: npm --version

Ejemplo: Incorporación de configuraciones

Por ejemplo, esta matriz ejecutará 10 trabajos, uno para cada combinación de os y version en la matriz, además de un trabajo para el valor os de windows-latest y el valor version de 17.

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [macos-latest, windows-latest, ubuntu-latest]
        version: [12, 14, 16]
        include:
          - os: windows-latest
            version: 17

Si no especificas ninguna variable de matriz, se ejecutarán todas las configuraciones de include. Por ejemplo, el siguiente flujo de trabajo ejecutaría dos trabajos, uno para cada entrada include. Esto permite aprovechar la estrategia de matriz sin tener una matriz totalmente rellenada.

jobs:
  includes_only:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - site: "production"
            datacenter: "site-a"
          - site: "staging"
            datacenter: "site-b"

jobs.<job_id>.strategy.matrix.exclude

Para quitar configuraciones específicas definidas en la matriz, usa jobs.<job_id>.strategy.matrix.exclude. Una configuración excluida solo debe ser una coincidencia parcial para que se excluya. Por ejemplo, el siguiente flujo de trabajo ejecutará nueve trabajos: un trabajo para cada una de las 12 configuraciones menos el trabajo excluido que coincide con {os: macos-latest, version: 12, environment: production} y los dos trabajos excluidos que coinciden con {os: windows-latest, version: 16}.

strategy:
  matrix:
    os: [macos-latest, windows-latest]
    version: [12, 14, 16]
    environment: [staging, production]
    exclude:
      - os: macos-latest
        version: 12
        environment: production
      - os: windows-latest
        version: 16
runs-on: ${{ matrix.os }}

jobs.<job_id>.strategy.fail-fast

Puedes controlar cómo se manejan los errores de trabajo con jobs.<job_id>.strategy.fail-fast y jobs.<job_id>.continue-on-error.

jobs.<job_id>.strategy.fail-fast se aplica a toda la matriz. Si jobs.<job_id>.strategy.fail-fast se establece en true, GitHub Enterprise Cloud cancelará todos los trabajos en curso y en cola en la matriz si se produce un error de cualquiera de los trabajos de esta. El valor predeterminado de esta propiedad es true.

jobs.<job_id>.continue-on-error se aplica a un solo trabajo. Si jobs.<job_id>.continue-on-error es true, el resto de los trabajos de la matriz seguirán ejecutándose aunque se produzca un error en el trabajo con jobs.<job_id>.continue-on-error: true.

Puede usar jobs.<job_id>.strategy.fail-fast y jobs.<job_id>.continue-on-error de forma conjunta. Por ejemplo, el flujo de trabajo siguiente iniciará cuatro trabajos. En cada trabajo, continue-on-error se determina mediante el valor de matrix.experimental. Si se produce un error en alguno de los trabajos con continue-on-error: false, se cancelarán todos los trabajos en curso o en la cola. Si se produce un error en el trabajo con continue-on-error: true, el resto de trabajos no se verán afectados.

jobs:
  test:
    runs-on: ubuntu-latest
    continue-on-error: ${{ matrix.experimental }}
    strategy:
      fail-fast: true
      matrix:
        version: [6, 7, 8]
        experimental: [false]
        include:
          - version: 9
            experimental: true

jobs.<job_id>.strategy.max-parallel

De forma predeterminada, GitHub Enterprise Cloud maximizará el número de trabajos ejecutados en paralelo en función de la disponibilidad del ejecutor. Para establecer el número máximo de trabajos que se pueden ejecutar simultáneamente al usar una estrategia de trabajo matrix, usa jobs.<job_id>.strategy.max-parallel.

Por ejemplo, el siguiente flujo de trabajo ejecutará un máximo de dos trabajos a la vez, incluso si hay ejecutores disponibles para ejecutar los seis trabajos a la vez.

jobs:
  example_matrix:
    strategy:
      max-parallel: 2
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]

jobs.<job_id>.continue-on-error

Previene que una ejecución de flujo de trabajo falle cuando un job falle. Establézcalo en true para permitir que se supere una ejecución de flujo de trabajo cuando se produce un error en este trabajo.

Ejemplo: Previniendo un job de matriz específico que falle desde una ejecución de flujo de trabajo que también falle

Puedes permitir que ciertos jobs en una matriz de jobs fallen sin que la ejecución de flujo de trabajo falle. Por ejemplo, si solo quiere permitir que se produzca un error en un trabajo experimental con node establecido en 15 sin que se ejecute el flujo de trabajo.

runs-on: ${{ matrix.os }}
continue-on-error: ${{ matrix.experimental }}
strategy:
  fail-fast: false
  matrix:
    node: [13, 14]
    os: [macos-latest, ubuntu-latest]
    experimental: [false]
    include:
      - node: 15
        os: ubuntu-latest
        experimental: true

jobs.<job_id>.container

Use jobs.<job_id>.container a fin de crear un contenedor para ejecutar cualquier paso de un trabajo que todavía no especifique un contenedor. Si tienes pasos que usan tanto acciones de script como de contenedor, las acciones de contenedor se ejecutarán como contenedores hermanos en la misma red con los mismos montajes de volumen.

Si no configura un objeto container, todos los pasos se ejecutarán directamente en el host especificado por runs-on, a menos que un paso haga referencia a una acción configurada para ejecutarse en un contenedor.

Ejemplo: Ejecución de un trabajo dentro de un contenedor

name: CI
on:
  push:
    branches: [ main ]
jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container:
      image: node:14.16
      env:
        NODE_ENV: development
      ports:
        - 80
      volumes:
        - my_docker_volume:/volume_mount
      options: --cpus 1
    steps:
      - name: Check for dockerenv file
        run: (ls /.dockerenv && echo Found dockerenv) || (echo No dockerenv)

Cuando solo especifique una imagen de contenedor, puede omitir la palabra clave image.

jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container: node:14.16

jobs.<job_id>.container.image

Use jobs.<job_id>.container.image a fin de definir la imagen de Docker que usar como contenedor para ejecutar la acción. El valor puede ser el nombre de imagen de Docker Hub o un nombre de registro.

jobs.<job_id>.container.credentials

Si el registro de contenedor de la imagen necesita la autenticación para extraer la imagen, puede usar jobs.<job_id>.container.credentials para establecer un valor map de username y password. Las credenciales son los mismos valores que se proporcionarían al comando docker login.

Ejemplo: definir las credenciales para un registro de contenedores

container:
  image: ghcr.io/owner/image
  credentials:
     username: ${{ github.actor }}
     password: ${{ secrets.github_token }}

jobs.<job_id>.container.env

Usa jobs.<job_id>.container.env para establecer un map de variables de entorno en el contenedor.

jobs.<job_id>.container.ports

Use jobs.<job_id>.container.ports para establecer un elemento array de puertos que se exponga en el contenedor.

jobs.<job_id>.container.volumes

Use jobs.<job_id>.container.volumes para establecer un valor array de volúmenes para que lo use contenedor. Puedes usar volúmenes para compartir datos entre servicios u otros pasos en un trabajo. Puedes especificar volúmenes Docker con nombre, volúmenes Docker anónimos o montajes de enlace en el host.

Para especificar un volumen, especifica la ruta de origen y destino:

<source>:<destinationPath>.

<source> es un nombre de volumen o una ruta absoluta en el equipo host y <destinationPath> es una ruta absoluta en el contenedor.

Ejemplo: Montaje de volúmenes en un contenedor

volumes:
  - my_docker_volume:/volume_mount
  - /data/my_data
  - /source/directory:/destination/directory

jobs.<job_id>.container.options

Use jobs.<job_id>.container.options para configurar opciones adicionales de recursos del contenedor de Docker. Para obtener una lista de opciones, vea "Opciones de docker create".

jobs.<job_id>.services

Se usa para hospedar contenedores de servicio para un trabajo en un flujo de trabajo. Los contenedores de servicio son útiles para crear bases de datos o servicios de caché como Redis. El ejecutor crea automáticamente una red Docker y administra el ciclo de vida de los contenedores de servicio.

Si configuras tu trabajo para que se ejecute en un contenedor, o si tu paso usa acciones del contenedor, no necesitas asignar puertos para acceder al servicio o a la acción. Docker expone automáticamente todos los puertos entre contenedores en la misma red de puente definida por el usuario de Docker. Puedes hacer referencia directamente al contenedor de servicio por su nombre de host. El nombre del host se correlaciona automáticamente con el nombre de la etiqueta que configuraste para el servicio en el flujo de trabajo.

Si configuras el trabajo para que se ejecute directamente en la máquina del ejecutor y tu paso no usa una acción de contenedor, debes asignar cualquier puerto del contenedor de servicio Docker que sea necesario para el host Docker (la máquina del ejecutor). Puedes acceder al contenedor de servicio utilizando host local y el puerto asignado.

Para más información sobre las diferencias entre los contenedores de servicios de red, vea "Acerca de los contenedores de servicios".

Ejemplo: Utilizando al host local

Este ejemplo crea dos servicios: nginx y Redis. Cuando especificas el puerto del host de Docker pero no el puerto del contenedor, el puerto del contenedor se asigna aleatoriamente a un puerto gratuito. GitHub establece el puerto de contenedor asignado en el contexto ${{job.services.<service_name>.ports}}. En este ejemplo, puede acceder a los puertos del contenedor de servicios mediante los contextos ${{ job.services.nginx.ports['8080'] }} y ${{ job.services.redis.ports['6379'] }}.

services:
  nginx:
    image: nginx
    # Map port 8080 on the Docker host to port 80 on the nginx container
    ports:
      - 8080:80
  redis:
    image: redis
    # Map TCP port 6379 on Docker host to a random free port on the Redis container
    ports:
      - 6379/tcp

jobs.<job_id>.services.<service_id>.image

La imagen Docker para usar como el contenedor de servicio para ejecutar la acción. El valor puede ser el nombre de la imagen de Docker Hub o un nombre de registro.

jobs.<job_id>.services.<service_id>.credentials

Si el registro de contenedor de la imagen necesita la autenticación para extraer la imagen, puede usar jobs.<job_id>.container.credentials para establecer un valor map de username y password. Las credenciales son los mismos valores que se proporcionarían al comando docker login.

Ejemplo de jobs.<job_id>.services.<service_id>.credentials

services:
  myservice1:
    image: ghcr.io/owner/myservice1
    credentials:
      username: ${{ github.actor }}
      password: ${{ secrets.github_token }}
  myservice2:
    image: dockerhub_org/myservice2
    credentials:
      username: ${{ secrets.DOCKER_USER }}
      password: ${{ secrets.DOCKER_PASSWORD }}

jobs.<job_id>.services.<service_id>.env

Establece un valor map de variables de entorno en el contenedor de servicios.

jobs.<job_id>.services.<service_id>.ports

Establece un valor array de puertos que se van a exponer en el contenedor de servicios.

jobs.<job_id>.services.<service_id>.volumes

Establece un valor array de volúmenes para el contenedor de servicios. Puedes usar volúmenes para compartir datos entre servicios u otros pasos en un trabajo. Puedes especificar volúmenes Docker con nombre, volúmenes Docker anónimos o montajes de enlace en el host.

Para especificar un volumen, especifica la ruta de origen y destino:

<source>:<destinationPath>.

<source> es un nombre de volumen o una ruta absoluta en el equipo host y <destinationPath> es una ruta absoluta en el contenedor.

Ejemplo de jobs.<job_id>.services.<service_id>.volumes

volumes:
  - my_docker_volume:/volume_mount
  - /data/my_data
  - /source/directory:/destination/directory

jobs.<job_id>.services.<service_id>.options

Opciones adicionales de recursos del contenedor Docker. Para obtener una lista de opciones, vea "Opciones de docker create".

jobs.<job_id>.uses

La ubicación y versión de un archivo de flujo de trabajo reutilizable a ejecutar como un job. Usa una de las siguientes sintaxis:

• {owner}/{repo}/.github/workflows/{filename}@{ref} para flujos de trabajo reutilizables en repositorios públicos, internos y privados.
• ./.github/workflows/{filename} para flujos de trabajo reutilizables en el mismo repositorio.

{ref} puede ser un SHA, una etiqueta de versión o un nombre de rama. Utilizar el SHA de la confirmación es lo más seguro para la estabilidad y seguridad. Para obtener más información, vea «». Si usas la segunda opción de sintaxis (sin {owner}/{repo} y @{ref}), el flujo de trabajo que se llama procede de la misma confirmación que el flujo de trabajo autor de la llamada.

Ejemplo de jobs.<job_id>.uses

jobs:
  call-workflow-1-in-local-repo:
    uses: octo-org/this-repo/.github/workflows/workflow-1.yml@172239021f7ba04fe7327647b213799853a9eb89
  call-workflow-2-in-local-repo:
    uses: ./.github/workflows/workflow-2.yml
  call-workflow-in-another-repo:
    uses: octo-org/another-repo/.github/workflows/workflow.yml@v1

Para obtener más información, vea «Reutilización de flujos de trabajo».

jobs.<job_id>.with

Cuando se utiliza un trabajo para llamar a un flujo de trabajo reutilizable, puede usar with para proporcionar un mapa de entradas que se pasen al flujo de trabajo llamado.

Cualquier entrada que pases debe coincidir con las especificaciones de la entrada que se define en el flujo de trabajo llamado.

A diferencia de jobs.<job_id>.steps[*].with, las entradas que se pasan con jobs.<job_id>.with no están disponibles como variables de entorno en el flujo de trabajo llamado. En su lugar, puede hacer referencia a las entradas mediante el contexto inputs.

Ejemplo de jobs.<job_id>.with

jobs:
  call-workflow:
    uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main
    with:
      username: mona

jobs.<job_id>.with.<input_id>

Un par que consiste de un identificador de secuencias para la entrada y del valor de entrada. El identificador debe coincidir con el nombre de una entrada definida por on.workflow_call.inputs.<inputs_id> en el flujo de trabajo llamado. El tipo de datos del valor debe coincidir con el tipo definido por on.workflow_call.inputs.<input_id>.type en el flujo de trabajo llamado.

Contextos de expresión permitidos: github y needs.

jobs.<job_id>.secrets

Cuando se utiliza un trabajo para llamar a un flujo de trabajo reutilizable, puede usar secrets para proporcionar un mapa de secretos que se pasen al flujo de trabajo llamado.

Cualquier secreto que pases debe coincidir con los nombres que se definen en el flujo de trabajo llamado.

Ejemplo de jobs.<job_id>.secrets

jobs:
  call-workflow:
    uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main
    secrets:
      access-token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

jobs.<job_id>.secrets.inherit

Usa la palabra clave inherit para pasar todos los secretos del flujo de trabajo que realiza la llamada al flujo de trabajo llamado. Esto incluye todos los secretos a los que tiene acceso el flujo de trabajo que realiza la llamada, es decir, los secretos de la organización, al repositorio y el entorno. La palabra clave inherit se puede usar para pasar secretos entre repositorios de la misma organización o entre organizaciones de la misma empresa.

Ejemplo de jobs.<job_id>.secrets.inherit

on:
  workflow_dispatch:

jobs:
  pass-secrets-to-workflow:
    uses: ./.github/workflows/called-workflow.yml
    secrets: inherit

on:
  workflow_call:

jobs:
  pass-secret-to-action:
    runs-on: ubuntu-latest
    steps:
      - name: Use a repo or org secret from the calling workflow.
        run: echo ${{ secrets.CALLING_WORKFLOW_SECRET }}

jobs.<job_id>.secrets.<secret_id>

Un par que consiste de un identificador de secuencias para el secreto y el valor de dicho secreto. El identificador debe coincidir con el nombre de un secreto definido por on.workflow_call.secrets.<secret_id> en el flujo de trabajo llamado.

Contextos de expresión permitidos: github, needs y secrets.

Hoja de datos de patrones de filtro

Puedes usar caracteres especiales en los filtros de ruta, de rama y de etiqueta.

• *: coincide con cero o más caracteres, pero no coincide con el carácter /. Por ejemplo, Octo* coincide con Octocat.
• **: coincide con cero o más repeticiones de cualquier carácter.
• ?: Coincide con cero o una repetición del carácter anterior.
• +: coincide con cero o más repeticiones del carácter anterior.
• [] coincide con un carácter que aparece en los corchetes o que se incluye en los rangos. Los rangos solo pueden incluir a-z, A-Zy 0-9. Por ejemplo, el rango [0-9a-z] coincide con cualquier dígito o letra minúscula. Por ejemplo, [CB]at coincide con Cat o Bat, y [1-2]00 coincide con 100 y 200.
• !: al comienzo de un patrón hace que se nieguen los patrones positivos anteriores. No tiene ningún significado especial si no es el primer caracter.

Los caracteres *, [ y ! son caracteres especiales en YAML. Si inicia un patrón con *, [ o !, debe incluirlo entre comillas. Además, si usas una secuencia de flujo con un patrón que contiene [ o ], este patrón debe incluirse entre comillas.

# Valid
branches:
  - '**/README.md'

# Invalid - creates a parse error that
# prevents your workflow from running.
branches:
  - **/README.md

# Valid
branches: [ main, 'release/v[0-9].[0-9]' ]

# Invalid - creates a parse error
branches: [ main, release/v[0-9].[0-9] ]

Para más información sobre la sintaxis de filtro de rama, etiqueta y ruta, vea "on.<push>.<branches|tags>", "on.<pull_request>.<branches|tags>" y "on.<push|pull_request>.paths".

Patrones para encontrar ramas y etiquetas

Patrones para encontrar rutas de archivos

Los patrones de ruta deben coincidir con toda la ruta y comenzar desde la raíz del repositorio.