Triggers y eventos

Un evento es una actividad específica en el repositorio que dispara un workflow run. La clave on de un workflow declara a qué eventos responde. En este capítulo recorremos los triggers más usados, desde los automáticos (push, PR, schedule) hasta los manuales y los custom.

push y pull_request

Los dos eventos más comunes. En su forma más simple, un string; para varios, un array:

on: [push, pull_request]

pull_request acepta un filtro types para reaccionar solo a ciertas transiciones del PR:

on:
  pull_request:
    types: [opened, synchronize, reopened]

• opened: se abre el PR.
• synchronize: se pushean commits nuevos a la rama del PR.
• reopened: se reabre un PR cerrado.

También podés filtrar por rama o por rutas de archivos:

on:
  push:
    branches: [main]
    paths: ["src/**"]

schedule: workflows por cron

on.schedule dispara el workflow en horarios fijos usando sintaxis cron POSIX (cinco campos: minuto, hora, día del mes, mes, día de la semana):

on:
  schedule:
    - cron: "0 6 * * 1"   # lunes a las 06:00 UTC
    - cron: "*/15 * * * *" # cada 15 minutos

Puntos a tener en cuenta:

• El intervalo mínimo es de cada 5 minutos.
• Podés declarar múltiples entradas cron en la misma lista.
• Los schedules corren siempre sobre la rama por defecto del repositorio.
• Los tiempos son en UTC.

Nota: bajo alta carga de la plataforma, los workflows programados pueden demorarse o incluso no dispararse exactamente a la hora indicada. No los uses para tareas donde el timing exacto sea crítico.

workflow_dispatch: disparo manual

Habilita un botón “Run workflow” en la UI (y el trigger vía API). Permite definir inputs tipados que el usuario completa al lanzarlo:

on:
  workflow_dispatch:
    inputs:
      entorno:
        description: "Entorno de despliegue"
        type: choice
        options: [staging, production]
        required: true
      dry_run:
        description: "Solo simular"
        type: boolean
        default: false

Los tipos disponibles son string, boolean, choice y environment. Dentro del workflow los referenciás con ${{ inputs.NOMBRE }} (o la forma equivalente ${{ github.event.inputs.NOMBRE }}):

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Desplegando a ${{ inputs.entorno }}"

repository_dispatch: eventos custom vía API

repository_dispatch te permite disparar un workflow desde un sistema externo haciendo una llamada a la API REST de GitHub. Es la herramienta para encadenar pipelines entre repositorios o integrar GitHub con otras plataformas (un webhook de tu CRM, otro repo que terminó su build, etc.):

on:
  repository_dispatch:
    types: [deploy-solicitado]

El sistema externo hace un POST al endpoint /repos/{owner}/{repo}/dispatches con un event_type que coincida con el filtro types, y puede adjuntar un payload custom accesible dentro del workflow.

Tabla resumen

Evento	Cuándo se dispara	Caso de uso típico
push	Se pushean commits a una rama	CI en cada cambio
pull_request	Se abre/actualiza un PR	Validar antes de mergear
schedule	En horarios cron (≥ 5 min)	Tareas nocturnas, limpieza, reportes
workflow_dispatch	Manualmente desde UI o API	Deploys a demanda con parámetros
repository_dispatch	POST a la API desde un sistema externo	Encadenar pipelines entre repos

---

Anterior → Capítulo 2: GitHub Actions — fundamentos · Siguiente → Capítulo 4: Actions avanzado