Nota: Los ejecutores hospedados en GitHub no son compatibles con GitHub Enterprise Server actualmente. Puedes encontrar más información sobre el soporte que se tiene planeado en el futuro en el Itinerario público de GitHub.
About YAML syntax for workflows
Workflow files use YAML syntax, and must have either a .yml
or .yaml
file extension. Si eres nuevo en YAML y quieres aprender más, consulta la guía "Aprende 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 page. If you omit name
, GitHub sets it to the workflow file path relative to the root of the repository.
on
Para activar un flujo de trabajo automáticamente, utiliza on
para definir los eventos que pueden causar que se ejecute el flujo de trabajo. Para obtener una lista de eventos disponibles, consulta "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 siguietnes secciones.
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 haga una subida a 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. Utiliza on.<event_name>.types
para definir el tipo de actividad de evento qeu activará una ejecución de flujo de trabajo.
Por ejemplo, el evento issue_comment
tiene los tipos de actividad created
, edited
y deleted
. Si tu flujo de trabajo activa el evento label
, este se ejecutará cada que se cree, edite o borre una etiqueta. Si especificas el tipo de actividad created
para el evento label
, tu flujo de trabajo se ejecutará cuando se cree una etiqueta pero no cuando esta se borre o edite.
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:
issue:
types:
- opened
- labeled
Para obtener más información acerca de cada evento y sus tipos de actividad, consulta "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 ocasiona que tu flujo de trabajo se ejecute únicamente cuando ocurra una subida a una rama que empate con el filtro branches
, en vez de cuando ocurra una subida.
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. Debes agregar dos puntos (:
) a todos los eventos, incluyendo aquellos sin configuración.
Por ejemplo, un flujo de trabajo con el siguiente valor on
se ejecutará cuando:
- Se crea una etiqueta
- Se hace una subida a la rama
main
en el repositorio - Se hace una subida a la rama habilitada por Páginas de GitHub
on:
label:
types:
- created
push:
branches:
- main
page_build:
on.<event_name>.types
Utiliza on.<event_name>.types
para definir el tipo de actividad que activará una ejecución de flujo de trabajo. La mayoría de los eventos GitHub son desencadenados por más de un tipo de actividad. Por ejemplo, la label
se activa cuando esta está como created
, edited
o deleted
. La palabra clave types
(tipos) te permite reducir la actividad que hace que se ejecute el flujo de trabajo. Cuando solo un tipo de actividad activa el evento webhook, la palabra clave types
(tipos) es innecesaria.
Puedes usar una matriz de tipos
de eventos. Para obtener más información acerca de 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
, puedes configurar un flujo de trabajo para que se ejecute únicamente para las solicitudes de cambio que apuntan a ramas específicas.
Utiliza el filtro branches
cuando quieras incluir patrones de nombre de rama o cuando quieras tanto incluirlos como excluirlos. Utiliza el filtro branches-ignore
cuando solo quieras excluir los patrones de nombre de rama. No puedes utilizar tanto el filtro branches
como branches-ignore
para el mismo evento en un flujo de trabajo.
Si defines branches
/branches-ignore
y paths
, el flujo de trabajo solo se ejecutará cuando ambos filtros se hayan satisfecho.
Las palabras clave branches
y branches-ignore
aceptan patrones globales que utilizan caracteres como *
, **
, +
, ?
, !
y otros para empatar con más de un nombre de rama. Si un nombre contiene cualquiera de estos caracteres y quieres una coincidencia literal, necesitas escapar a cada uno de estos caracteres especiales con \
. Para obtener más información sobre los patrones globales, consulta "Hoja de información para filtrar patrones".
Ejemplo: Incluir ramas
Los patrones que se definen en branches
se evalúan contra el nombre de ref de Git. Por ejemplo, el siguiente flujo de trabajo se ejecutaría siempre que exista un evento pull_request
para una solicitud de cambios que apunte a:
- Una rama de nombre
main
(refs/heads/main
) - Una rama de nombre
mona/octocat
(refs/heads/mona/octocat
) - Una rama cuyo nombre inicie con
releases/
, tal comoreleases/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 empata con el de branches-ignore
, el flujo de trabajo no se ejecutará. Los patrones que se definen en branches
se evalúan contra el nombre de ref de Git. Por ejemplo, el siguiente flujo de trabajo se ejecutaría siempre que haya un evento de pull_request
a menos de que la solicitud de cambios apunte a:
- Una rama de nombre
mona/octocat
(refs/heads/mona/octocat
) - Una rama cuyo nombre empata con
releases/**-alpha
, comoreleases/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 puedes utilizar branches
y branches-ignore
para filtrar el mismo evento en un mismo flujo de trabajo. Si quieres tanto incluir como excluir patrones de rama para un solo evento, utiliza el filtro branches
junto con el carácter !
para indicar qué ramas deberían excluirse.
Si defines una rama con el carácter !
, también debes definir por lo mismo una rama sin el carácter !
. Si solo quieres excluir ramas, utiliza branches-ignore
en su lugar.
El orden en que defines los patrones importa.
- Un patrón negativo de coincidencia (con prefijo
!
) luego de una coincidencia positiva excluirá la ref 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 los eventos de pull_request
para aquellas solicitudes de cambios que apunten a releases/10
o a releases/beta/mona
, pero no para aquellas que apunten a releases/10-alpha
o releases/beta/3-alpha
, ya que 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>
Cuando utilices el evento push
, podrás configurar un flujo de trabajo para que se ejecute en ramas o etiquetas específicas.
Utiliza el filtro branches
cuando quieras incluir patrones de nombre de rama o cuando quieras tanto incluirlos como excluirlos. Utiliza el filtro branches-ignore
cuando solo quieras excluir los patrones de nombre de rama. No puedes utilizar tanto el filtro branches
como branches-ignore
para el mismo evento en un flujo de trabajo.
Utiliza el filtro de tags
cuando quieras incluir los patrones de nombre de etiqueta o cuando quieras tanto incluirlos como excluirlos. Utiliza el filtro tags-ignore
cuando solo quieras excluir los patrones de nombre de etiqueta. No puedes utilizar ambos filtros, tags
y tags-ignore
, para el mismo evento en un flujo de trabajo.
Si defines únicamente tags
/tags-ignore
o solo branches
/branches-ignore
, el flujo de trabajo no se ejecutará para los eventos que afecten una Git ref indefinida. Si no defines tags
/tags-ignore
ni branches
/branches-ignore
, el flujo de trabajo se ejecutará para los eventos que afectan ya sea ramas o etiquetas. Si defines branches
/branches-ignore
y paths
, el flujo de trabajo solo se ejecutará cuando ambos filtros se hayan satisfecho.
Las palabras clave branches
, branches-ignore
, tags
, y tags-ignore
aceptan patrones globales que utilizan caracteres como *
, **
, +
, ?
, !
y otros para empatar con más de una rama o nombre de etiqueta. Si un nombre contiene cualquiera de estos caracteres y quieres tener una coincidencia literal, necesitas escapar cada uno de estos caracteres especiales con una \
. Para obtener más información sobre los patrones globales, consulta "Hoja de información para filtrar patrones".
Ejemplo: Incluyendo ramas y etiquetas
Los patrones definidos en branches
y tags
se evalúan con el nombre de ref de Git. Por ejemplo, el siguiente flujo de trabajo se ejecutaría siempre que hubiera un evento de push
para:
- Una rama de nombre
main
(refs/heads/main
) - Una rama de nombre
mona/octocat
(refs/heads/mona/octocat
) - Una rama cuyo nombre inicie con
releases/
, tal comoreleases/10
(refs/heads/releases/10
) - Una etiqueta de nombre
v2
(refs/tags/v2
) - Una etiqueta cuyo nombre inicie con
v1.
, tal comov1.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 empata con el de branches-ignore
o tags-ignore
, no se ejecutará el flujo de trabajo. Los patrones definidos en branches
y tags
se evalúan con el nombre de ref de Git. Por ejemplo, el siguiente flujo de trabajo se ejecutaría siempre que haya un evento push
, a menos de que el evento push
sea para:
- Una rama de nombre
mona/octocat
(refs/heads/mona/octocat
) - Una rama cuyo nombre empate con
releases/**-alpha
, tal comobeta/3-alpha
(refs/releases/beta/3-alpha
) - Una etiqueta de nombre
v2
(refs/tags/v2
) - Una etiqueta cuyo nombre inicie con
v1.
, tal comov1.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 puedes utilizar branches
y branches-ignore
para filtrar el mismo evento en un solo flujo de trabajo. De forma similar, no puedes utilizar tags
y tags-ignore
para filtrar el mismo evento en un solo flujo de trabajo. Si quieres incluir y excluir patrones de etiquetas o ramas para un solo evento, utiliza el filtro branches
o tags
junto con el carácter !
para indicar qué ramas o etiquetas deberían excluirse.
Si defines una rama con el carácter !
, también debes definir por lo mismo una rama sin el carácter !
. Si solo quieres excluir ramas, utiliza branches-ignore
en su lugar. Del mismo modo, si defines una etiqueta con el carácter !
, también debes definir por lo menos una etiqueta sin el carácter !
. Si solo quieres excluir las etiquetas, utiliza tags-ignore
en su lugar.
El orden en que defines los patrones importa.
- Un patrón negativo de coincidencia (con prefijo
!
) luego de una coincidencia positiva excluirá la ref 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 las subidas a releases/10
o releases/beta/mona
, pero no en releases/10-alpha
o releases/beta/3-alpha
porque el patrón negativo !releases/**-alpha
le sigue al patrón positivo.
on:
push:
branches:
- 'releases/**'
- '!releases/**-alpha'
on.<push|pull_request|pull_request_target>.<paths|paths-ignore>
Cuando utilices los eventos push
y pull_request
, puedes configurar un flujo de trabajo para que se ejecute con base en qué rutas de archivo cambiaron. Los filtros de ruta no se evalúan para subidas de etiquetas.
Utiliza el filtro paths
cuando quieras incluir los patrones de ruta de archivo o cuando quieras tanto incluirlos como excluirlos. Utiliza el filtro paths-ignore
cuando solo quieras excluir los patrones de ruta de archivo. No puedes utilizar tanto el filtro de paths
como el de paths-ignore
juntos en el mismo evento en un flujo de trabajo.
Si defines tanto branches
/branches-ignore
como paths
, el flujo de trabajo solo se ejecutará cuando ambos filtros se hayan satisfecho.
Las palabras clave paths
y paths-ignore
aceptan patrones globales que utilicen los caracteres de comodín *
y **
para empatar con más de un nombre de ruta. Para obtener más información, consulta "Hoja de referencia de patrones de filtro".
Ejemplo: Incluyendo rutas
Si al menos una ruta coincide con un patrón del filtro de rutas
, se ejecuta el flujo de trabajo. Por ejemplo, el siguiente flujo de trabajo se ejecutaría siempre que subieras un archivo de JavaScript (.js
).
on:
push:
paths:
- '**.js'
Nota: Si se omite un flujo de trabajo debido a filtrado de ruta, filtrado de rama o a un mensaje de confirmación, entonces las verificaciones asociadas con este flujo de trabajo permanecerán en un estado de "Pendiente". Las solicitudes de cambios que requieran que esas verificaciones tengan éxito quedarán bloqueadas para fusión. Para obtener más información, consulta la sección "Manejar verificaciones omitidas pero requeridas".
Ejemplo: Excluir las rutas
Cuando todos los nombres de ruta coincidan con los patrones en paths-ignore
, el flujo de trabajo no se ejecutará. Si alguno de los nombres de ruta no empatan con los patrones en paths-ignore
, incluso si algunos de ellos sí lo hacen, el flujo de trabajo se ejecutará.
Un flujo de trabajo con el siguiente filtro de ruta solo se ejecutará en los eventos de subida
que incluyan al menos un archivo externo al directorio docs
en la raíz del repositorio.
on:
push:
paths-ignore:
- 'docs/**'
Ejemplo: Incluir y excluir rutas
No puedes utilizar paths
y paths-ignore
para filtrar el mismo evento en un solo flujo de trabajo. Si quieres tanto incluir como excluir patrones de ruta para un solo evento, utiliza el filtro de paths
en conjunto con el carácter !
para indicar qué rutas deben excluirse.
Si defines una ruta con el carácter !
, también debes definir por lo menos una ruta sin el carácter !
. Si solo quieres excluir rutas, utiliza paths-ignore
en su lugar.
El orden en que defines los patrones importa:
- Una coincidencia de patrón negativo (con prefijo
!
) luego de una coincidencia positiva excluirá la ruta. - Un patrón de coincidencia positiva luego de una coincidencia negativa excluirá nuevamente la ruta.
Este ejemplo se ejecuta cada vez que el evento de subida
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 subida que haya cambiado sub-project/index.js
o sub-project/src/index.js
desencadenará una ejecución de flujo de trabajo, pero una subida que cambie solo sub-project/docs/readme.md
no lo hará.
on:
push:
paths:
- 'sub-project/**'
- '!sub-project/docs/**'
Comparaciones de diferencias de Git
Nota: Si subes más de 1,000 confirmaciones o si GitHub no genera el diff debido a que se excedió el tiempo, el flujo de trabajo siempre se ejecutará.
El filtro determina si un flujo de trabajo se debe ejecutar al evaluar los archivos modificados y al ejecutarlos comparándolos 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 extracción: 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, cuando la rama de tema se sincronizó por última vez con la rama base.
- Subidas a ramas existentes: una diferencia de dos puntos compara las SHA de encabezado y de base directamente entre sí.
- Subidas a ramas nuevas: una diferencia de dos puntos comparada con el padre del antepasado de la confirmación más profunda subida.
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 comparar ramas en las solicitudes de extracción".
on.schedule
Puedes utilizar on.schedule
para definir un itinerario de tiempo para tus flujos de trabajo. Puedes programar un flujo de trabajo para que se ejecute en horarios UTC específicos usando sintaxis de cron 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 programar flujos de trabajo es 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 * * *'
Se puede activar un flujo de trabajo sencillo mediante eventos múltiples de schedule
. Puedes acceder al evento de programación que activó el flujo de trabajo mediante el contexto github.event.schedule
. Este ejemplo activa el flujo de trabajo para que se ejecute a las 5:30 UTC cada lunes a viernes, pero se salta el paso Not on Monday or Wednesday
para los lunes y 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 acerca de la sintaxis cron, consulta la sección "Eventos que activan flujos de trabajo".
on.workflow_run.<branches|branches-ignore>
Cuando utilices el evento workflow_run
, puedes especificar qué ramas debe ejecutar el flujo de trabajo activador para que se active tu flujo.
Los filtros de branches
y branches-ignore
aceptan patrones globales que utilizan caracteres como *
, **
, +
, ?
, !
y otros para empatar con más de un nombre de rama. Si un nombre contiene cualquiera de estos caracteres y quieres tener una coincidencia literal, necesitas escapar cada uno de estos caracteres especiales con una \
. Para obtener más información sobre los patrones globales, consulta "Hoja de información para filtrar patrones".
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 inicie con 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 llamado Build
se ejecute en una rama que no se llame canary
:
on:
workflow_run:
workflows: ["Build"]
types: [requested]
branches-ignore:
- "canary"
No puedes utilizar tanto el filtro branches
como branches-ignore
para el mismo evento en un flujo de trabajo. Si quieres tanto incluir como excluir patrones de rama para un solo evento, utiliza 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 llamado Build
se ejecute en una rama que se llame releases/10
o releases/beta/mona
pero no en las de nombre releases/10-alpha
, releases/beta/3-alpha
o main
.
on:
workflow_run:
workflows: ["Build"]
types: [requested]
branches:
- 'releases/**'
- '!releases/**-alpha'
on.workflow_dispatch.inputs
Cuando se utiliza el evento workflow_dispatch
, puedes especificar opcionalmente entradas que se pasan al flujo de trabajo.
El flujo de trabajo activado recibe las entradas en el contexto github.event.inputs
. Para obtener más información, consulta la sección "Contextos".
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 }}
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
Utiliza defaults
para crear un map
mapa de ajustes predeterminados que aplicarán a todos los jobs 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, consulta la sección 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 utilizar defaults.run
para proporcionar opciones predeterminadas de shell
y working-directory
para todos los pasos de run
en un flujo de trabajo. También puedes configurar ajustes predeterminados para run
que solo estén disponibles para un job. Para obtener más información, consulta jobs.<job_id>.defaults.run
. No podrás 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
jobs
Una ejecución de flujo de trabajo se conforma de uno o más jobs
, los cuales se ejecutan en paralelo predeterminadamente. Para ejecutar trabajos de manera secuencial, puedes definir dependencias en otros trabajos utilizando la palabra clave jobs.<job_id>.needs
.
Cada job se ejecuta en un ambiente ejecutor que especifica 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 obtener más información, consulta las secciones "Límites de uso y facturación" para los ejecutores hospedados en GitHub y "Acerca de los ejecutores auto hospedados" para los límites de uso de los ejecutores auto-hospedados.
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 obtener más información, consulta la sección "Jobs de los Flujos de Trabajo".
jobs.<job_id>
Utiliza jobs.<job_id>
para darle a tu job un identificador único. 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>
con una cadena que sea exclusiva del objeto jobs
. El <job_id>
debe comenzar con una letra o _
y debe contener solo caracteres alfanuméricos, -
, o _
.
Ejemplo: Crear jobs
En este ejemplo, se crearon dos jobs y sus valores de 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
Utiliza jobs.<job_id>.name
para configurar un nombre para el job, lo cuál se muestra en la IU GitHub.
jobs.<job_id>.needs
Utiliza jobs.<job_id>.needs
para identificar cualquier job que deba completarse con éxito antes de que este se ejecute. 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 jobs que se necesitan el uno al otro, una falla aplica a todos los jobs en la cadena de dependencias desde el punto de falla en adelante.
Ejemplo: Requerir jobs dependientes exitosos
jobs:
job1:
job2:
needs: job1
job3:
needs: [job1, job2]
En este ejemplo, job1
debe completarse con éxito antes de que job2
comience, y job3
espera a quejob1
y job2
se completen.
En este ejemplo, los trabajos se ejecutan de manera secuencial:
job1
job2
job3
Ejemplo: No requerir jobs dependientes exitosos
jobs:
job1:
job2:
needs: job1
job3:
if: ${{ always() }}
needs: [job1, job2]
En este ejemplo, job3
utiliza la expresión condicional always()
para que siempre se ejecute después de que el job1
y el job2
se hayan completado, sin importar si tuvieron éxito o no. Para obtener más información, consulta la sección "Expresiones".
jobs.<job_id>.if
Puedes utilizar el condicional jobs.<job_id>.if
para prevenir que un job se ejecute a menos de que una condición se cumpla. Puedes usar cualquier contexto y expresión admitidos para crear un condicional.
Podrías omitir la sintaxis de expresión cuando utilizas expresiones en un condicional if
(${{ }}
) ya que GitHub evalúa automáticamente el condicional if
como una expresión. Para obtener más información, consulta la sección "Expresiones".
Ejemplo: Solo ejecutar un job para un repositorio específico
Este ejemplo utiliza if
para controla cuándo se puede ejecutar el job production-deploy
. Este solo se ejecutará si el repositorio se llama octo-repo-prod
y está dentro de la organización octo-org
. De otra forma, el job se marcará como skipped.
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
Utiliza jobs.<job_id>.runs-on
para definir el tipo de máquina en la cuál ejecutar el job. Puedes proporcionar a runs-on
como una secuencia simple o como un arreglo de secuencias. Si especificas un arreglo de secuencias, tu flujo de trabajo se ejecutará en un ejecutor auto-hospedado cuyas etiquetas empaten con todos los valores de runs-on
que se hayan especificado, en caso de que estén disponibles. Si te gustaría ejecutar tu flujo de trabajo en máquinas múltiples, utiliza jobs.<job_id>.strategy
.
Nota: Los ejecutores hospedados en GitHub no son compatibles con GitHub Enterprise Server actualmente. Puedes encontrar más información sobre el soporte que se tiene planeado en el futuro en el Itinerario público de GitHub.
Elegir los ejecutores hospedados en GitHub
Si usas un ejecutor alojado GitHub, cada trabajo se ejecuta en una nueva instancia de un entorno virtual especificado por runs-on
.
Los tipos de ejecutores alojados GitHub disponibles son:
Entorno virtual | Etiqueta de flujo de trabajo YAML | Notas |
---|---|---|
Windows Server 2022 | windows-latest o windows-2022 |
La etiqueta de windows-latest actualmente utiliza la imagen de ejecutor de Windows Server 2022.
|
Windows Server 2019 | windows-2019 |
|
Ubuntu 22.04 | ubuntu-22.04 |
Ubuntu 22.04 se encuentra actualmente en beta público. |
Ubuntu 20.04 | ubuntu-latest o ubuntu-20.04 |
|
Ubuntu 18.04 | ubuntu-18.04 |
|
macOS Monterey 12 | macos-12 |
|
macOS Big Sur 11 | macos-latest or macos-11 |
La etiqueta de macos-latest actualmente utiliza la imagen de ejecutor de macOS 11.
|
macOS Catalina 10.15 | macos-10.15 |
Nota: Los ambientes virtuales más recientes
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 obsoletizadas se proporcionan "tal cual", "con todos sus fallos" y "conforme estén disponibles" y se les excluye del acuerdo de nivel de servicio y de la garantía. El soporte al cliente podría no cubrir las imágenes beta.
Ejemplo: Especificar un sistema operativo
runs-on: ubuntu-latest
Para obtener más información, consulta "Entornos virtuales para ejecutores alojados de GitHub".
Elegir los ejecutores auto-hospedados
Para especificar un ejecutor auto-hospedado para tu trabajo, configura runs-on
en tu archivo de flujo de trabajo con las etiquetas de dicho ejecutor.
Todos los ejecutores auto-hospedados tienen la etiqueta self-hosted
. El utilizar únicamente esta etiqueta seleccionará cualquier ejecutor auto-hospedado. Para seleccionar los ejecutores que cumplen con ciertos criterios, tales como el sistema operativo o arquitectura, te recomendamos proporcionar un arreglo de etiquetas que comience con self-hosted
(este se debe listar primero) y que luego incluya etiquetas adicionales conforme lo requieras. 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 de self-hosted
no se requiere, te recomendamos ampliamente especificarla cuando utilices ejecutores auto-hospedados para garantizar que tu trabajo no especifique algún ejecutor hospedado en GitHub futuro o actual por accidente.
Ejemplo: Utilizar las etiquetas para la selección de ejecutores
runs-on: [self-hosted, linux]
Para obtener más información, consulta "Acerca de los ejecutores autoalojados" y "Usar ejecutores autoalojados en un flujo de trabajo".
jobs.<job_id>.environment
Utiliza jobs.<job_id>.environment
para definir el ambiente al que hace referencia el job. 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 obtener más información, consulta la sección "Utilizar ambientes para despliegue".
Puedes proporcionar el ambiente como solo el name
de éste, o como un objeto de ambiente con el name
y url
. La URL mapea hacia environment_url
en la API de despliegues. Para obtener más información sobre la API de despliegues, consulta la sección "Despliegues".
Ejemplo: Utilizar un solo nombre de ambiente
environment: staging_environment
Ejemplo: Utilizar una URL y nombre de ambiente
environment:
name: production_environment
url: https://github.com
La URL puede ser una expresión y puede utilizar cualquier contexto, excepto el de secrets
. Para obtener más información sobre las expresiones, consulta la sección "Expresiones".
Ejemplo: Utilizar una salida como URL
environment:
name: production_environment
url: ${{ steps.step_id.outputs.url_output }}
jobs.<job_id>.outputs
Puedes utilizar jobs.<job_id>.outputs
para crear un map
de salidas para un job. Las salidas de un job se encuentran disponibles para todos los jobs descendentes que dependan de este job. Para obtener más información sobre la definición de dependencias, consulta jobs.<job_id>.needs
.
Outputs are Unicode strings, and can be a maximum of 1 MB. The total of all outputs in a workflow run can be a maximum of 50 MB.
Las salidas de job que contengan expresiones se evaluarán en el ejecutor al fin de cada job. Las salidas que contienen secretos se redactan en el ejecutor y no se envían a GitHub Actions.
Para utilizar salidas de jobs en un job dependiente, puedes utilizar el contexto needs
. Para obtener más información, consulta "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
Utiliza jobs.<job_id>.defaults
para crear un map
de ajustes predeterminados que aplicarán a todos los pasos del job. También puedes configurar ajustes predeterminados para todo el flujo de trabajo. Para obtener más información, consulta 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
Utiliza jobs.<job_id>.defaults.run
para propocionar un shell
y working-directory
predeterminados para todos los pasos de run
en el job. No se permiten las expresiones ni contexto en esta sección.
Puedes proporcionar opciones predeterminadas de shell
y working-directory
para todos los pasos de run
en un job. También puedes configurar ajustes predeterminados para run
para todo el flujo de trabajo. Para obtener más información, consulta jobs.defaults.run
. No podrás 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 opciones de paso de run
predeterminadas para un job
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.
Podrías omitir la sintaxis de expresión cuando utilizas expresiones en un condicional if
(${{ }}
) ya que GitHub evalúa automáticamente el 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 number. 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.
- Using the specific major action version allows you to receive critical fixes and security patches while still maintaining compatibility. It also assures that your workflow should still work.
- 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 platform | shell parameter | Description | Command run internally |
---|---|---|---|
All | bash | The 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} |
All | pwsh | The PowerShell Core. GitHub appends the extension .ps1 to your script name. | pwsh -command ". '{0}'" |
All | python | Executes the python command. | python {0} |
Linux / macOS | sh | The fallback behavior for non-Windows platforms if no shell is provided and bash is not found in the path. | sh -e {0} |
Windows | cmd | GitHub appends the extension .cmd to your script name and substitutes for {0} . | %ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}"" . |
Windows | pwsh | This 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}'" . |
Windows | powershell | The 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
: Default forbash
and built-inshell
. It is also the default when you don't provide an option on non-Windows platforms. - You can opt out of fail-fast and take full control 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.
- Fail-fast behavior using
-
powershell
/pwsh
- Fail-fast behavior when possible. For
pwsh
andpowershell
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}
, orpowershell -Command "& '{0}'"
, depending on need.
- Fail-fast behavior when possible. For
-
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 previoussh
andpwsh
default behavior and is thecmd.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:
- Document required arguments in the action's README and omit them from the
CMD
instruction. - Use defaults that allow using the action without specifying any
args
. - 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: The GITHUB_TOKEN
expires when a job finishes or after a maximum of 24 hours. 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. A matrix strategy lets you use variables in a single job definition to automatically create multiple job runs that are based the combinations of the variables. For example, you can use a matrix strategy to test your code in multiple versions of a language or on multiple operating systems. For more information, see "Using a matrix for your jobs."
jobs.<job_id>.strategy.matrix
Utiliza jobs.<job_id>.strategy.matrix
para definir una matriz de configuraciones de jobs diferentes. Within your matrix, define one or more variables followed by an array of values. For example, the following matrix has a variable called version
with the value [10, 12, 14]
and a variable called os
with the value [ubuntu-latest, windows-latest]
:
jobs:
example_matrix:
strategy:
matrix:
version: [10, 12, 14]
os: [ubuntu-latest, windows-latest]
A job will run for each possible combination of the variables. In this example, the workflow will run six jobs, one for each combination of the os
and version
variables.
By default, GitHub Enterprise Server will maximize the number of jobs run in parallel depending on runner availability. The order of the variables in the matrix determines the order in which the jobs are created. The first variable you define will be the first job that is created in your workflow run. For example, the above matrix will create the jobs in the following order:
{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}
A matrix will generate a maximum of 256 jobs per workflow run. Este límite aplica tanto a los ejecutores hospedados en GitHub Enterprise Server como a los auto-hospedados.
The variables that you define become properties in the matrix
context, and you can reference the property in other areas of your workflow file. In this example, you can use matrix.version
and matrix.os
to access the current value of version
and os
that the job is using. Para obtener más información, consulta "Contextos".
Example: Using a single-dimension matrix
You can specify a single variable to create a single-dimension matrix.
For example, the following workflow defines the variable version
with the values [10, 12, 14]
. The workflow will run three jobs, one for each value in the variable. Each job will access the version
value through the matrix.version
context and pass the value as node-version
to the actions/setup-node
action.
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
You can specify multiple variables to create a multi-dimensional matrix. Un job se ejecutará para cada combinación posible de las variables.
For example, the following workflow specifies two variables:
- Two operating systems specified in the
os
variable - Three Node.js versions specified in the
version
variable
The workflow will run six jobs, one for each combination of the os
and version
variables. Each job will set the runs-on
value to the current os
value and will pass the current version
value to the actions/setup-node
action.
jobs:
example_matrix:
strategy:
matrix:
os: [ubuntu-18.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
You can use contexts to create matrices. Para obtener más información sobre los contextos, consulta la sección "Contextos".
For example, the following workflow triggers on the repository_dispatch
event and uses information from the event payload to build the matrix. When a repository dispatch event is created with a payload like the one below, the matrix version
variable will have a value of [12, 14, 16]
. For more information about the repository_dispatch
trigger, see "Events that trigger workflows."
{
"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
Use jobs.<job_id>.strategy.matrix.include
to expand existing matrix configurations or to add new configurations. The value of include
is a list of objects.
For each object in the include
list, the key:value pairs in the object will be added to each of the matrix combinations if none of the key:value pairs overwrite any of the original matrix values. If the object cannot be added to any of the matrix combinations, a new matrix combination will be created instead. Note that the original matrix values will not be overwritten, but added matrix values can be overwritten.
For example, this matrix:
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
will result in six jobs with the following matrix combinations:
{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}
following this logic:
{color: green}
is added to all of the original matrix combinations because it can be added without overwriting any part of the original combinations.{color: pink, animal: cat}
addscolor:pink
only to the original matrix combinations that includeanimal: cat
. This overwrites thecolor: green
that was added by the previousinclude
entry.{fruit: apple, shape: circle}
addsshape: circle
only to the original matrix combinations that includefruit: apple
.{fruit: banana}
cannot be added to any original matrix combination without overwriting a value, so it is added as an additional matrix combination.{fruit: banana, animal: cat}
cannot be added to any original matrix combination without overwriting a value, so it is added as an additional matrix combination. It does not add to the{fruit: banana}
matrix combination because that combination was not one of the original matrix combinations.
Example: Expanding configurations
For example, the following workflow will run six jobs, one for each combination of os
and node
. When the job for the os
value of windows-latest
and node
value of 16
runs, an additional variable called npm
with the value of 6
will be included in the job.
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
For example, this matrix will run 10 jobs, one for each combination of os
and version
in the matrix, plus a job for the os
value of windows-latest
and version
value of 17
.
jobs:
example_matrix:
strategy:
matrix:
os: [macos-latest, windows-latest, ubuntu-latest]
version: [12, 14, 16]
include:
- os: windows-latest
version: 17
If you don't specify any matrix variables, all configurations under include
will run. For example, the following workflow would run two jobs, one for each include
entry. This lets you take advantage of the matrix strategy without having a fully populated matrix.
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
To remove specific configurations defined in the matrix, use jobs.<job_id>.strategy.matrix.exclude
. An excluded configuration only has to be a partial match for it to be excluded. For example, the following workflow will run nine jobs: one job for each of the 12 configurations, minus the one excluded job that matches {os: macos-latest, version: 12, environment: production}
, and the two excluded jobs that match {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 te permite utilizar include
para volver a agregar combinaciones que se excluyeron previamente.
jobs.<job_id>.strategy.fail-fast
Puedes controlar cómo se manejan los fallos de los jobs con jobs.<job_id>.strategy.fail-fast
y jobs.<job_id>.continue-on-error
.
jobs.<job_id>.strategy.fail-fast
aplica a toda la matriz. Si configuras a jobs.<job_id>.strategy.fail-fast
como true
, GitHub Enterprise Server cancelará todos los jobs de la matriz que estén en cola y en progreso en caos de que cualquiera de ellos falle. Esta propiedad se predetermina en true
.
jobs.<job_id>.continue-on-error
aplica a un solo job. Si jobs.<job_id>.continue-on-error
es true
, otros jobs en la matriz seguirán ejecutándose, incluso si el job con jobs.<job_id>.continue-on-error: true
falla.
Puedes utilizar jobs.<job_id>.strategy.fail-fast
y jobs.<job_id>.continue-on-error
juntos. Por ejemplo, el siguiente flujo de trabajo iniciará cuatro jobs. Para cada job, continue-on-error
se determina mediante el valor de matrix.experimental
. Si cualquiera de los jobs con continue-on-error: false
falla, todos los jobs que estén en progreso o en cola se cancelarán. Si el job con continue-on-error: true
falla, los otros 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
By default, GitHub Enterprise Server will maximize the number of jobs run in parallel depending on runner availability. Para configurar la cantidad máxima de jobs que puedan ejecutarse simultáneamente al utilizar una estrategia de jobs de matrix
, utiliza jobs.<job_id>.strategy.max-parallel
.
Por ejemplo, el siguiente flujo de trabajo ejecutará un máximo de dos jobs a la vez, incluso si hay ejecutores disponibles para ejecutar los seis jobs al mismo tiempo.
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-18.04]
experimental: [false]
include:
- node: 15
os: ubuntu-18.04
experimental: true
jobs.<job_id>.container
Nota: Si tus flujos de trabajo utilizan acciones de contenedor de Docker, contenedores de jobs o de servicio, entonces debes utilizar un ejecutor 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.
Utiliza jobs.<job_id>.container
para crear un contenedor para ejecutar cualquier paso en un job que aún 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 configuras un container
, todos los pasos se ejecutan directamente en el host especificado por runs-on
a menos que un paso se refiera a una acción configurada para ejecutarse en un contenedor.
Ejemplo: Ejecutar un job 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 especificas una imagen de contenedor, puedes omitir la palabra clave image
.
jobs:
container-test-job:
runs-on: ubuntu-latest
container: node:14.16
jobs.<job_id>.container.image
Utiliza jobs.<job_id>.container.image
para definir la imagen de Docker a utilizar como el 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 del contenedor de la imagen requiere autenticación para extraerla, puedes utilizar jobs.<job_id>.container.credentials
para configurar un map
del username
y password
. Las credenciales son los mismos valores que proporcionarías al comando de 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
Utiliza jobs.<job_id>.container.env
para configurar un map
de variables ambientales en el contenedor.
jobs.<job_id>.container.ports
Utiliza jobs.<job_id>.container.ports
para configurar un array
de puertos para exponer en el contenedor.
jobs.<job_id>.container.volumes
Utiliza jobs.<job_id>.container.volumes
para configurar un array
de volúmenes para que lo utilice el 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 la máquina host, y <destinationPath>
es una ruta absoluta en el contenedor.
Ejemplo: Montar volúmenes en un contenedor
volumes:
- my_docker_volume:/volume_mount
- /data/my_data
- /source/directory:/destination/directory
jobs.<job_id>.container.options
Utiliza jobs.<job_id>.container.options
para configurar opciones adicionales de recursos para los contenedores de Docker. Para obtener una lista de opciones, consulta las opciones "crear docker
".
Advertencia: La opción --network
no es compatible.
jobs.<job_id>.services
Nota: Si tus flujos de trabajo utilizan acciones de contenedor de Docker, contenedores de jobs o de servicio, entonces debes utilizar un ejecutor 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 del contenedor de la imagen requiere autenticación para extraerla, puedes utilizar jobs.<job_id>.container.credentials
para configurar un map
del username
y password
. Las credenciales son los mismos valores que proporcionarías al comando de 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*
matchesOctocat
.**
: 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 includea-z
,A-Z
, and0-9
. For example, the range[0-9a-z]
matches any digit or lowercase letter. For example,[CB]at
matchesCat
orBat
and[1-2]00
matches100
and200
.!
: 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.
# Valid
- '**/README.md'
# Invalid - creates a parse error that
# prevents your workflow from running.
- **/README.md
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
Pattern | Description | Example 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.
Pattern | Description of matches | Example 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/**/*.md | A 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 |