Skip to main content

Esta versión de GitHub Enterprise se discontinuó el 2022-10-12. No se realizarán lanzamientos de patch, ni siquiera para problemas de seguridad críticos. Para obtener rendimiento mejorado, seguridad mejorada y nuevas características, actualice a la versión más reciente de GitHub Enterprise. Para obtener ayuda con la actualización, póngase en contacto con el soporte técnico de GitHub Enterprise.

Workflow syntax for GitHub Actions

En este artículo

A workflow is a configurable automated process made up of one or more jobs. You must create a YAML file to define your workflow configuration.

Nota: Actualmente los ejecutores hospedados en GitHub no se admiten en GitHub Enterprise Server. Puede ver más información sobre la compatibilidad futura planeada en GitHub public roadmap.

About YAML syntax for workflows

Workflow files use YAML syntax, and must have either a .yml or .yaml file extension. Si no está familiarizado con YAML y quiere obtener más información, vea "Aprenda YAML en Y minutos".

You must store workflow files in the .github/workflows directory of your repository.

name

The name of your workflow. GitHub displays the names of your workflows on your repository's "Actions" tab. If you omit name, GitHub sets it to the workflow file path relative to the root of the repository.

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 un itinerario de tiempos. 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 la "Hoja de referencia de patrones de filtro".

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'

Nota: Si se omite un flujo de trabajo debido a un filtrado de ruta, filtrado de rama o mensaje de confirmación, las comprobaciones asociadas a ese flujo de trabajo permanecerán en estado "Pendiente". Se bloqueará la fusión mediante combinación de una solicitud de incorporación de cambios que requiera esas comprobaciones para realizarse correctamente. Para obtener más información, consulta "Control de comprobaciones omitidas pero necesarias".

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

Nota: Si insertas más de 1000 confirmaciones o si GitHub no genera las diferencias debido a que se agota el tiempo de espera, el flujo de trabajo siempre se ejecutará.

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, consulta "Acerca de la comparación de ramas en las solicitudes de incorporación de cambios".

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_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.inputs

When using the workflow_dispatch event, you can optionally specify inputs that are passed to the workflow.

The triggered workflow receives the inputs in the github.event.inputs context. For more information, see "Contexts."

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning' 
      print_tags:
        description: 'True to print to STDOUT'
        required: true 
      tags:
        description: 'Test scenario tags'
        required: true 

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

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 "Autenticación en un flujo de trabajo".

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
  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 más información, vea "[Administración de la configuración de GitHub Actions para un repositorio](/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

A map of environment variables that are available to the steps of all jobs in the workflow. You can also set environment variables that are only available to the steps of a single job or to a single step. For more information, see jobs.<job_id>.env and jobs.<job_id>.steps[*].env.

Variables in the env map cannot be defined in terms of other variables in the map.

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

Example

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 y facturació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 Enterprise Server. Para más información, vea "Trabajos de flujo de trabajo".

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 más información, vea "Autenticación en un flujo de trabajo".

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
  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 más información, vea "[Administración de la configuración de GitHub Actions para un repositorio](/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@v4

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.

Al usar expresiones en una condicional if, puede omitir la sintaxis de la expresión (${{ }}) porque GitHub evalúa de forma automática la condicional if como una expresión. Para más información, vea "Expresiones".

Ejemplo: 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.

YAML
name: example-workflow
on: [push]
jobs:
  production-deploy:
    if: github.repository == 'octo-org/octo-repo-prod'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        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. Puede proporcionar runs-on como una cadena única o como una matriz de cadenas. Si especifica una matriz de cadenas, el flujo de trabajo se ejecutará en un ejecutor autohospedado cuyas etiquetas coinciden con todos los valores runs-on especificados, si están disponibles. Si quiere ejecutar el flujo de trabajo en varias máquinas, use jobs.<job_id>.strategy.

Nota: Actualmente los ejecutores hospedados en GitHub no se admiten en GitHub Enterprise Server. Puede ver más información sobre la compatibilidad futura planeada en GitHub public roadmap.

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:

Imagen del ejecutor Etiqueta de flujo de trabajo YAML Notas
Windows Server 2022 windows-latest o windows-2022 La etiqueta windows-latest usa actualmente la imagen del ejecutor de Windows Server 2022.
Windows Server 2019 windows-2019
Ubuntu 22.04 ubuntu-22.04
Ubuntu 20.04 ubuntu-latest o ubuntu-20.04
Ubuntu 18.04 [en desuso] ubuntu-18.04 Realiza la migración a ubuntu-20.04 o ubuntu-22.04. Para obtener más información, consulta esta entrada de blog de GitHub.
macOS Monterey 12 macos-12
macOS Big Sur 11 macos-latest o macos-11 La etiqueta macos-latest usa actualmente la imagen del ejecutor de macOS 11.
macOS Catalina 10.15 [en desuso] macos-10.15 Realiza la migración a macOS-11 o macOS-12. Para obtener más información, consulta esta entrada de blog de GitHub.

Nota: Las imágenes de ejecutores -latest son las últimas imágenes estables que proporciona GitHub y puede que no sean las versiones más recientes de los sistemas operativos disponibles desde los proveedores de estos.

Nota: Las imágenes beta y en desuso se proporcionan "tal cual", "con todos sus fallos" y "conforme estén disponibles" y están excluidas del acuerdo de nivel de servicio y de la garantía. El soporte al cliente podría no cubrir las imágenes beta.

Ejemplo: Especificación de un sistema operativo

runs-on: ubuntu-latest

Para obtener más información, consulte "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 más información, vea "Acerca de los ejecutores autohospedados" y "Uso de ejecutores autohospedados en un flujo de trabajo".

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

Nota: Cuando se especifica la simultaneidad a nivel de trabajo, no se garantiza el orden para los trabajos ni las ejecuciones que se ponen en cola con una diferencia de 5 minutos entre sí

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 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 "::set-output name=test::hello"
      - id: step2
        run: echo "::set-output name=test::world"
  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - run: echo ${{needs.job1.outputs.output1}} ${{needs.job1.outputs.output2}}

jobs.<job_id>.env

A map of environment variables that are available to all steps in the job. You can also set environment variables for the entire workflow or an individual step. For more information, see env and jobs.<job_id>.steps[*].env.

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

Example

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

A job contains a sequence of tasks called steps. Steps can run commands, run setup tasks, or run an action in your repository, a public repository, or an action published in a Docker registry. Not all steps run actions, but all actions run as a step. Each step runs in its own process in the runner environment and has access to the workspace and filesystem. Because steps run in their own process, changes to environment variables are not preserved between steps. GitHub provides built-in steps to set up and complete a job.

You can run an unlimited number of steps as long as you are within the workflow usage limits. For more information, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.

Example

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

A unique identifier for the step. You can use the id to reference the step in contexts. For more information, see "Contexts."

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

You can use the if conditional to prevent a step from running unless a condition is met. You can use any supported context and expression to create a conditional.

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. For more information, see "Expressions."

Example: Using contexts

This step only runs when the event type is a pull_request and the event action is 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.

Example: Using status check functions

The my backup step only runs when the previous step of a job fails. For more information, see "Expressions."

steps:
  - name: My first step
    uses: octo-org/action-name@main
  - name: My backup step
    if: ${{ failure() }}
    uses: actions/heroku@1.0.0

Example: Using secrets

Secrets cannot be directly referenced in if: conditionals. Instead, consider setting secrets as job-level environment variables, then referencing the environment variables to conditionally run steps in the job.

If a secret has not been set, the return value of an expression referencing the secret (such as ${{ secrets.SuperSecret }} in the example) will be an empty string.

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.'

For more information, see "Context availability" and "Encrypted secrets."

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

A name for your step to display on GitHub.

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

Selects an action to run as part of a step in your job. An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, or in a published Docker container image.

We strongly recommend that you include the version of the action you are using by specifying a Git ref, SHA, or Docker tag. If you don't specify a version, it could break your workflows or cause unexpected behavior when the action owner publishes an update.

  • Using the commit SHA of a released action version is the safest for stability and security.
  • If the action publishes major version tags, you should expect to receive critical fixes and security patches while still retaining compatibility. Note that this behavior is at the discretion of the action's author.
  • Using the default branch of an action may be convenient, but if someone releases a new major version with a breaking change, your workflow could break.

Some actions require inputs that you must set using the with keyword. Review the action's README file to determine the inputs required.

Actions are either JavaScript files or Docker containers. If the action you're using is a Docker container you must run the job in a Linux environment. For more details, see runs-on.

Example: Using versioned actions

steps:
  # Reference a specific commit
  - uses: actions/checkout@a81bbbf8298c0fa03ea29cdc473d45769f953675
  # Reference the major version of a release
  - uses: actions/checkout@v2
  # Reference a specific version
  - uses: actions/checkout@v2.2.0
  # Reference a branch
  - uses: actions/checkout@main

Example: Using a public action

{owner}/{repo}@{ref}

You can specify a branch, ref, or SHA in a public GitHub repository.

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

Example: Using a public action in a subdirectory

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

A subdirectory in a public GitHub repository at a specific branch, ref, or SHA.

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

Example: Using an action in the same repository as the workflow

./path/to/dir

The path to the directory that contains the action in your workflow's repository. You must check out your repository before using the action.

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

Example: Using a Docker Hub action

docker://{image}:{tag}

A Docker image published on Docker Hub.

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

Example: Using a Docker public registry action

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

A Docker image in a public registry. This example uses the Google Container Registry at gcr.io.

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

Example: Using an action inside a different private repository than the workflow

Your workflow must checkout the private repository and reference the action locally. Generate a personal access token and add the token as an encrypted secret. For more information, see "Creating a personal access token" and "Encrypted secrets."

Replace PERSONAL_ACCESS_TOKEN in the example with the name of your secret.

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v2
        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

Runs command-line programs using the operating system's shell. If you do not provide a name, the step name will default to the text specified in the run command.

Commands run using non-login shells by default. You can choose a different shell and customize the shell used to run commands. For more information, see jobs.<job_id>.steps[*].shell.

Each run keyword represents a new process and shell in the runner environment. When you provide multi-line commands, each line runs in the same shell. For example:

  • A single-line command:

    - name: Install Dependencies
      run: npm install
    
  • A multi-line command:

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

Using the working-directory keyword, you can specify the working directory of where to run the command.

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

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

You can override the default shell settings in the runner's operating system using the shell keyword. You can use built-in shell keywords, or you can define a custom set of shell options. The shell command that is run internally executes a temporary file that contains the commands specified in the run keyword.

Supported platformshell parameterDescriptionCommand run internally
Linux / macOSunspecifiedThe default shell on non-Windows platforms. Note that this runs a different command to when bash is specified explicitly. If bash is not found in the path, this is treated as sh.bash -e {0}
AllbashThe default shell on non-Windows platforms with a fallback to sh. When specifying a bash shell on Windows, the bash shell included with Git for Windows is used.bash --noprofile --norc -eo pipefail {0}
AllpwshThe PowerShell Core. GitHub appends the extension .ps1 to your script name.pwsh -command ". '{0}'"
AllpythonExecutes the python command.python {0}
Linux / macOSshThe fallback behavior for non-Windows platforms if no shell is provided and bash is not found in the path.sh -e {0}
WindowscmdGitHub appends the extension .cmd to your script name and substitutes for {0}.%ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}"".
WindowspwshThis is the default shell used on Windows. The PowerShell Core. GitHub appends the extension .ps1 to your script name. If your self-hosted Windows runner does not have PowerShell Core installed, then PowerShell Desktop is used instead.pwsh -command ". '{0}'".
WindowspowershellThe PowerShell Desktop. GitHub appends the extension .ps1 to your script name.powershell -command ". '{0}'".

Example: Running a script using bash

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

Example: Running a script using Windows cmd

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

Example: Running a script using PowerShell Core

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

Example: Using PowerShell Desktop to run a script

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

Example: Running a python script

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

Custom shell

You can set the shell value to a template string using command […options] {0} [..more_options]. GitHub interprets the first whitespace-delimited word of the string as the command, and inserts the file name for the temporary script at {0}.

For example:

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

The command used, perl in this example, must be installed on the runner.

Exit codes and error action preference

For built-in shell keywords, we provide the following defaults that are executed by GitHub-hosted runners. You should use these guidelines when running shell scripts.

  • bash/sh:

    • Fail-fast behavior using set -eo pipefail: This option is set when shell: bash is explicitly specified. It is not applied by default.
    • You can take full control over shell parameters by providing a template string to the shell options. For example, bash {0}.
    • sh-like shells exit with the exit code of the last command executed in a script, which is also the default behavior for actions. The runner will report the status of the step as fail/succeed based on this exit code.
  • powershell/pwsh

    • Fail-fast behavior when possible. For pwsh and powershell built-in shell, we will prepend $ErrorActionPreference = 'stop' to script contents.
    • We append if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } to powershell scripts so action statuses reflect the script's last exit code.
    • Users can always opt out by not using the built-in shell, and providing a custom shell option like: pwsh -File {0}, or powershell -Command "& '{0}'", depending on need.
  • cmd

    • There doesn't seem to be a way to fully opt into fail-fast behavior other than writing your script to check each error code and respond accordingly. Because we can't actually provide that behavior by default, you need to write this behavior into your script.
    • cmd.exe will exit with the error level of the last program it executed, and it will return the error code to the runner. This behavior is internally consistent with the previous sh and pwsh default behavior and is the cmd.exe default, so this behavior remains intact.

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

A map of the input parameters defined by the action. Each input parameter is a key/value pair. Input parameters are set as environment variables. The variable is prefixed with INPUT_ and converted to upper case.

Example

Defines the three input parameters (first_name, middle_name, and last_name) defined by the hello_world action. These input variables will be accessible to the hello-world action as INPUT_FIRST_NAME, INPUT_MIDDLE_NAME, and INPUT_LAST_NAME environment variables.

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

A string that defines the inputs for a Docker container. GitHub passes the args to the container's ENTRYPOINT when the container starts up. An array of strings is not supported by this parameter.

Example

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.

The args are used in place of the CMD instruction in a Dockerfile. If you use CMD in your Dockerfile, use the guidelines ordered by preference:

  1. Document required arguments in the action's README and omit them from the CMD instruction.
  2. Use defaults that allow using the action without specifying any args.
  3. If the action exposes a --help flag, or something similar, use that as the default to make your action self-documenting.

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

Overrides the Docker ENTRYPOINT in the Dockerfile, or sets it if one wasn't already specified. Unlike the Docker ENTRYPOINT instruction which has a shell and exec form, entrypoint keyword accepts only a single string defining the executable to be run.

Example

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

The entrypoint keyword is meant to be used with Docker container actions, but you can also use it with JavaScript actions that don't define any inputs.

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

Sets environment variables for steps to use in the runner environment. You can also set environment variables for the entire workflow or a job. For more information, see env and jobs.<job_id>.env.

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

Public actions may specify expected environment variables in the README file. If you are setting a secret in an environment variable, you must set secrets using the secrets context. For more information, see "Using environment variables" and "Contexts."

Example

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

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

Prevents a job from failing when a step fails. Set to true to allow a job to pass when this step fails.

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

The maximum number of minutes to run the step before killing the process.

jobs.<job_id>.timeout-minutes

The maximum number of minutes to let a job run before GitHub automatically cancels it. Default: 360

If the timeout exceeds the job execution time limit for the runner, the job will be canceled when the execution time limit is met instead. For more information about job execution time limits, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.

Note: GITHUB_TOKEN expira cuando finaliza un trabajo o después de un máximo de 24 horas. For self-hosted runners, the token may be the limiting factor if the job timeout is greater than 24 hours. For more information on the GITHUB_TOKEN, see "About the GITHUB_TOKEN secret."

jobs.<job_id>.strategy

Use jobs.<job_id>.strategy to use a matrix strategy for your jobs. 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. For more information, see "Using a matrix for your jobs."

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 Server 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 Server.

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 más información, vea "Contextos".

Example: Using a single-dimension matrix

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@v2
        with:
          node-version: ${{ matrix.version }}

Example: Using a multi-dimension matrix

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@v2
        with:
          node-version: ${{ matrix.version }}

Example: Using contexts to create 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@v2
        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.

Example: Expanding configurations

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@v2
        with:
          node-version: ${{ matrix.node }}
      - if: ${{ matrix.npm }}
        run: npm install -g npm@${{ matrix.npm }}
      - run: npm --version

Example: Adding configurations

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 }}

Nota: Todas las combinaciones de include se procesan después de exclude. Esto le permite usar include para volver a agregar combinaciones previamente excluidas.

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 Server 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 Server 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

Prevents a workflow run from failing when a job fails. Set to true to allow a workflow run to pass when this job fails.

Example: Preventing a specific failing matrix job from failing a workflow run

You can allow specific jobs in a job matrix to fail without failing the workflow run. For example, if you wanted to only allow an experimental job with node set to 15 to fail without failing the workflow run.

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

Nota: Si en los flujos de trabajo se usan acciones de contenedor de Docker, contenedores de trabajos o de servicios, tendrá que utilizar un ejecutor de Linux:

  • Si estás utilizando ejecutores hospedados en GitHub, debes utilizar un ejecutor de Ubuntu.
  • Si estás utilizando ejecutores auto-hospedados, debes utilizar una máquina Linux como tu ejecutor, y ésta debe tener Docker instalado.

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.

Nota: El shell predeterminado para los pasos run dentro de un contenedor es sh en lugar de bash. Esto se puede invalidar con jobs.<job_id>.defaults.run o jobs.<job_id>.steps[*].shell.

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

YAML
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".

Advertencia: No se admite la opción --network.

jobs.<job_id>.services

Nota: Si en los flujos de trabajo se usan acciones de contenedor de Docker, contenedores de trabajos o de servicios, tendrá que utilizar un ejecutor de Linux:

  • Si estás utilizando ejecutores hospedados en GitHub, debes utilizar un ejecutor de Ubuntu.
  • Si estás utilizando ejecutores auto-hospedados, debes utilizar una máquina Linux como tu ejecutor, y ésta debe tener Docker instalado.

Used to host service containers for a job in a workflow. Service containers are useful for creating databases or cache services like Redis. The runner automatically creates a Docker network and manages the life cycle of the service containers.

If you configure your job to run in a container, or your step uses container actions, you don't need to map ports to access the service or action. Docker automatically exposes all ports between containers on the same Docker user-defined bridge network. You can directly reference the service container by its hostname. The hostname is automatically mapped to the label name you configure for the service in the workflow.

If you configure the job to run directly on the runner machine and your step doesn't use a container action, you must map any required Docker service container ports to the Docker host (the runner machine). You can access the service container using localhost and the mapped port.

For more information about the differences between networking service containers, see "About service containers."

Example: Using localhost

This example creates two services: nginx and redis. When you specify the Docker host port but not the container port, the container port is randomly assigned to a free port. GitHub sets the assigned container port in the ${{job.services.<service_name>.ports}} context. In this example, you can access the service container ports using the ${{ job.services.nginx.ports['8080'] }} and ${{ job.services.redis.ports['6379'] }} contexts.

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

The Docker image to use as the service container to run the action. The value can be the Docker Hub image name or a registry name.

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.

Example

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

Sets a map of environment variables in the service container.

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

Sets an array of ports to expose on the service container.

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

Sets an array of volumes for the service container to use. You can use volumes to share data between services or other steps in a job. You can specify named Docker volumes, anonymous Docker volumes, or bind mounts on the host.

To specify a volume, you specify the source and destination path:

<source>:<destinationPath>.

The <source> is a volume name or an absolute path on the host machine, and <destinationPath> is an absolute path in the container.

Example

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

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

Additional Docker container resource options. For a list of options, see "docker create options."

Warning: The --network option is not supported.

Filter pattern cheat sheet

You can use special characters in path, branch, and tag filters.

  • *: Matches zero or more characters, but does not match the / character. For example, Octo* matches Octocat.
  • **: Matches zero or more of any character.
  • ?: Matches zero or one of the preceding character.
  • +: Matches one or more of the preceding character.
  • [] Matches one character listed in the brackets or included in ranges. Ranges can only include a-z, A-Z, and 0-9. For example, the range[0-9a-z] matches any digit or lowercase letter. For example, [CB]at matches Cat or Bat and [1-2]00 matches 100 and 200.
  • !: At the start of a pattern makes it negate previous positive patterns. It has no special meaning if not the first character.

The characters *, [, and ! are special characters in YAML. If you start a pattern with *, [, or !, you must enclose the pattern in quotes. Also, if you use a flow sequence with a pattern containing [ and/or ], the pattern must be enclosed in quotes.

# 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] ]

For more information about branch, tag, and path filter syntax, see "on.<push>.<branches|tags>", "on.<pull_request>.<branches|tags>", and "on.<push|pull_request>.paths."

Patterns to match branches and tags

PatternDescriptionExample matches
feature/*The * wildcard matches any character, but does not match slash (/).feature/my-branch

feature/your-branch
feature/**The ** wildcard matches any character including slash (/) in branch and tag names.feature/beta-a/my-branch

feature/your-branch

feature/mona/the/octocat
main

releases/mona-the-octocat
Matches the exact name of a branch or tag name.main

releases/mona-the-octocat
'*'Matches all branch and tag names that don't contain a slash (/). The * character is a special character in YAML. When you start a pattern with *, you must use quotes.main

releases
'**'Matches all branch and tag names. This is the default behavior when you don't use a branches or tags filter.all/the/branches

every/tag
'*feature'The * character is a special character in YAML. When you start a pattern with *, you must use quotes.mona-feature

feature

ver-10-feature
v2*Matches branch and tag names that start with v2.v2

v2.0

v2.9
v[12].[0-9]+.[0-9]+Matches all semantic versioning branches and tags with major version 1 or 2.v1.10.1

v2.0.0

Patterns to match file paths

Path patterns must match the whole path, and start from the repository's root.

PatternDescription of matchesExample matches
'*'The * wildcard matches any character, but does not match slash (/). The * character is a special character in YAML. When you start a pattern with *, you must use quotes.README.md

server.rb
'*.jsx?'The ? character matches zero or one of the preceding character.page.js

page.jsx
'**'The ** wildcard matches any character including slash (/). This is the default behavior when you don't use a path filter.all/the/files.md
'*.js'The * wildcard matches any character, but does not match slash (/). Matches all .js files at the root of the repository.app.js

index.js
'**.js'Matches all .js files in the repository.index.js

js/index.js

src/js/app.js
docs/*All files within the root of the docs directory, at the root of the repository.docs/README.md

docs/file.txt
docs/**Any files in the /docs directory at the root of the repository.docs/README.md

docs/mona/octocat.txt
docs/**/*.mdA file with a .md suffix anywhere in the docs directory.docs/README.md

docs/mona/hello-world.md

docs/a/markdown/file.md
'**/docs/**'Any files in a docs directory anywhere in the repository.docs/hello.md

dir/docs/my-file.txt

space/docs/plan/space.doc
'**/README.md'A README.md file anywhere in the repository.README.md

js/README.md
'**/*src/**'Any file in a folder with a src suffix anywhere in the repository.a/src/app.js

my-src/code/js/app.js
'**/*-post.md'A file with the suffix -post.md anywhere in the repository.my-post.md

path/their-post.md
'**/migrate-*.sql'A file with the prefix migrate- and suffix .sql anywhere in the repository.migrate-10909.sql

db/migrate-v1.0.sql

db/sept/migrate-v1.sql
*.md

!README.md
Using an exclamation mark (!) in front of a pattern negates it. When a file matches a pattern and also matches a negative pattern defined later in the file, the file will not be included.hello.md

Does not match

README.md

docs/hello.md
*.md

!README.md

README*
Patterns are checked sequentially. A pattern that negates a previous pattern will re-include file paths.hello.md

README.md

README.doc