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/
, 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 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
, 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 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/
, comoreleases/10
(refs/heads/releases/10
) - Una etiqueta denominada
v2
(refs/tags/v2
) - Una etiqueta cuyo nombre comienza por
v1.
, 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 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
, comobeta/3-alpha
(refs/releases/beta/3-alpha
) - Una etiqueta denominada
v2
(refs/tags/v2
) - Una etiqueta cuyo nombre comienza por
v1.
, 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 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:
job1
job2
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.
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 platform | shell parameter | Description | Command run internally |
---|---|---|---|
Linux / macOS | unspecified | The 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} |
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
: This option is set whenshell: 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.
- 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: 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}
agregacolor:pink
solo a las combinaciones de matriz originales que incluyenanimal: cat
. Esto sobrescribe elcolor: green
que ha sido agregado por la entrada anteriorinclude
.{fruit: apple, shape: circle}
agregashape: circle
solo a las combinaciones de matriz originales que incluyenfruit: 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
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*
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. 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
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 |