Saltar al contenido

Cron en GitHub Actions: UTC, retrasos y errores comunes

Última actualización

Un workflow programado parece sencillo, pero varias reglas sorprenden a menudo: las horas se expresan en UTC, las ejecuciones pueden empezar con retraso o saltarse, y la programación solo funciona desde la rama predeterminada. Esta guía explica la sintaxis y el comportamiento que debe tener en cuenta al planificar.

La sintaxis

on:
  schedule:
    - cron: "30 5 * * 1-5"   # 05:30 UTC, Monday to Friday
    - cron: "0 */6 * * *"    # every 6 hours, on the hour
  workflow_dispatch:         # lets you run it by hand too

Una expresión cron tiene cinco campos:

 minute (0-59)
 | hour (0-23)
 | | day of month (1-31)
 | | | month (1-12 or JAN-DEC)
 | | | | day of week (0-6 or SUN-SAT)
 | | | | |
 * * * * *

Supported operators: (any), , (list), - (range), / (step). GitHub uses POSIX cron syntax. Extensions from other systems, like @daily, L, ? or a seconds field, do not work. Quote the expression in YAML, because a leading is otherwise parsed as a YAML alias and the file is invalid.

El generador de cron convierte programaciones expresadas en lenguaje natural en expresiones y muestra las próximas ejecuciones, la forma más sencilla de evitar errores.

Todo está en UTC de forma predeterminada

De forma predeterminada, GitHub evalúa las programaciones en UTC. La documentación actual de GitHub también describe una clave opcional timezone que acepta un nombre de zona horaria IANA (por ejemplo, America/New_York), así que consulte la referencia de eventos antes de confiar en la solución alternativa de dos programaciones que se explica más abajo. Si no la define, no se aplica ningún ajuste por horario de verano. Un trabajo configurado con 0 9 * * * se ejecuta a las 09:00 UTC, es decir, a las 05:00 en Nueva York en verano y a las 04:00 en invierno. Si necesita "09:00 hora local, todo el año", tiene dos opciones:

  • Programe las dos horas UTC que podrían coincidir y salga pronto en la que no corresponda:
on:
  schedule:
    - cron: "0 13 * * 1-5"   # 09:00 EDT
    - cron: "0 14 * * 1-5"   # 09:00 EST
jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - name: Only proceed at 09:00 New York time
        id: gate
        run: |
          hour=$(TZ=America/New_York date +%H)
          [ "$hour" = "09" ] && echo "go=true" >> "$GITHUB_OUTPUT" || echo "go=false" >> "$GITHUB_OUTPUT"
      - if: steps.gate.outputs.go == 'true'
        run: ./send-report.sh
  • Acepte un desfase de una hora dos veces al año e indíquelo en un comentario.

Las programaciones no son exactas

La documentación de GitHub indica que los workflows programados pueden retrasarse en periodos de alta carga, y que los momentos de alta carga incluyen el inicio de cada hora. En la práctica, los trabajos 0 * * * * suelen empezar con varios minutos de retraso, y ocasionalmente se pierden ejecuciones con mucha carga. Por tanto:

  • Evite el inicio de la hora. Use minutos impares, como 17 3 * * *. Es la forma más sencilla de reducir el retraso.
  • No confíe en la precisión horaria. Un workflow que debe ejecutarse exactamente a las 09:00 debería activarse mediante otro sistema, como un programador en la nube que llame a la API de workflow_dispatch.
  • Haga que los trabajos sean idempotentes. Use el momento que procesan (una ventana calculada a partir de la hora del evento de la ejecución) en lugar de "ahora menos 1 hora", de modo que una ejecución retrasada o repetida produzca el mismo resultado.
  • Intervalo mínimo: el intervalo más corto que admite GitHub es de 5 minutos. Para algo más frecuente, use otro disparador o un servicio de larga duración.

Dónde se ejecutan las programaciones

  • Un workflow programado se ejecuta sobre el último commit de la rama predeterminada. El archivo del workflow en otras ramas se ignora para la programación. Para probar un cambio, envíelo a la rama predeterminada o ejecute el workflow manualmente con workflow_dispatch sobre su rama.
  • Las ejecuciones programadas usan la rama predeterminada del repositorio para GITHUB_REF; por tanto, checkout obtiene la rama predeterminada salvo que especifique otra cosa.
  • El actor es el usuario que modificó por última vez la línea cron del archivo. Si ese usuario se elimina de la organización, es posible que las ejecuciones dejen de funcionar; si es necesario, confirme una edición trivial de la línea cron con una cuenta de servicio.

La regla de los 60 días

En los repositorios públicos, GitHub desactiva automáticamente los workflows programados tras 60 días sin actividad en el repositorio. Recibirá un correo electrónico y deberá volver a habilitarlo, ya sea en la interfaz de Actions o con:

gh workflow enable schedule-workflow.yml

Según la documentación de GitHub, los repositorios privados no se ven afectados por esta regla. Si depende de una programación en un repositorio público con poca actividad, añada un paso que lo mantenga activo, por ejemplo un commit periódico de un bot, o use un programador externo.

La programación de GitHub Actions no se ejecuta

Si su programación no se ejecuta, o el síntoma "la programación de GitHub Actions no funciona" es intermitente, compruebe estos puntos en orden:

  1. Solo la rama predeterminada. Los workflows programados se ejecutan desde el último commit de la rama predeterminada. Un workflow que existe solo en una rama de funcionalidad nunca se activa.
  2. La regla de los 60 días. En un repositorio público, los workflows programados se desactivan automáticamente cuando no ha habido actividad en el repositorio durante 60 días. Vuelva a habilitarlos en la pestaña Actions.
  3. Sintaxis y comillas. Una expresión cron no válida, o un * inicial sin comillas, hace que el workflow no sea válido. Compruébelo con el generador de cron y el validador de YAML.
  4. Intervalo mínimo. El intervalo más corto es de una vez cada 5 minutos.
  5. Retrasos por carga. Las ejecuciones pueden empezar tarde o perderse con mucha carga, sobre todo al inicio de la hora. Use minutos impares como 17.
  6. Actions desactivado o el workflow desactivado, sobre todo en forks, donde los workflows programados están apagados hasta que se habilitan.
  7. Confusión con UTC. La ejecución puede haberse producido a la hora UTC y no a su hora local.

La programación de GitHub Actions no funciona tras un cambio

Las ediciones de la línea cron se aplican desde la rama predeterminada una vez fusionadas, y la siguiente ejecución sigue la nueva expresión. Añada workflow_dispatch: para probar el cuerpo del trabajo sin tener que esperar.

Errores comunes

ErrorResultadoSolución
/5 * * * sin comillasError de análisis de YAMLPonga la cadena entre comillas
Suponer la hora localLas ejecuciones se producen con horas de diferencia y cambian con el horario de veranoConvertir a UTC
0 0 31 * *Solo se ejecuta en los meses que tienen 31 díasUse 0 0 1 * * o calcule el último día en el job
Día del mes y día de la semana configurados a la vezSe combinan con OR, no con AND (comportamiento POSIX)Configure solo uno y compruebe el otro dentro del job
Pruebas en una rama de funcionalidadLa programación nunca se activaHaga merge a la rama predeterminada o use workflow_dispatch
Job pesado cada hora en el minuto 0Inicios retrasados y picos de recursosUse minutos impares
Olvidar la concurrencyEjecuciones solapadas si una es lentaAñada concurrency con un grupo

Añada un grupo de concurrency para que una ejecución lenta no se solape con la siguiente:

concurrency:
  group: nightly-report
  cancel-in-progress: false

Coste de las programaciones

Las programaciones se facturan como cualquier otra ejecución, incluidas las fallidas. Un job de 5 minutos cada 15 minutos supone 480 minutos facturados al mes en Linux, unos $2.88 a $0.006 por minuto, y el coste se acumula en muchos repositorios. Los jobs cron que consultan si ha ocurrido algo a menudo pueden sustituirse por disparadores de eventos (push, release, repository_dispatch, webhooks). Utilice también timeout-minutes y coloque primero una comprobación previa económica, de modo que el job termine en segundos cuando no haya nada que hacer. Consulte cómo reducir la factura de GitHub Actions y estime el uso con la calculadora de costes de Actions.

Buenos usos de las programaciones

  • Ejecuciones nocturnas completas de pruebas y búsqueda de pruebas inestables (consulte cómo tratar las pruebas inestables).
  • Análisis de dependencias y de seguridad.
  • Precalentamiento de la caché de la rama predeterminada, para que las PR empiecen con la caché caliente (guía de caché).
  • Limpieza de issues obsoletos y generación de informes.

Preguntas frecuentes

¿Puedo programar en mi zona horaria?

GitHub documenta un campo opcional timezone con el nombre de una zona IANA en las entradas de schedule; confírmelo en la documentación vigente para su plan. Sin él, convierta a UTC, o programe dos horas UTC y condicione por la hora local como se muestra arriba.

¿Por qué no se ejecuta mi programación de GitHub Actions?

Lo más habitual es que el workflow no esté en la rama predeterminada, que el repositorio haya estado inactivo durante 60 días (repositorios públicos), que el YAML no sea válido o que la ejecución se retrase por la carga. Consulte la lista de comprobación anterior.

¿Por qué mi programación de GitHub Actions solo funciona a veces?

GitHub advierte de que los eventos programados pueden retrasarse o perderse con carga alta, sobre todo al inicio de la hora. Pase a un minuto de baja demanda y diseñe el job para tolerar una ejecución tardía o perdida.

¿Por qué mi programación se ejecutó tarde o se saltó una ejecución?

GitHub advierte de que la carga puede retrasar las ejecuciones programadas, sobre todo al inicio de la hora. Use minutos de baja demanda y diseñe para tolerar retrasos.

¿Puedo tener varias programaciones en un mismo workflow?

Sí, enumere varias entradas cron. Use github.event.schedule para saber cuál se ha activado.

¿Cómo ejecuto el mismo workflow manualmente?

Añada workflow_dispatch: y use «Run workflow» en la pestaña Actions o gh workflow run.

Pruébelo

Use el generador de cron gratuito para revisar las próximas horas de ejecución antes de confirmar los cambios. Si sus jobs programados son pesados, el modo de comparación de compiler.dev muestra cuánto cuesta el mismo job nocturno en runners más rápidos.

Ejecute este workflow en compiler.dev Sin tarjeta · 200 minutos gratuitos

Pruébelo gratis