workflow_dispatch: ejecuciones manuales seguras para agentes

workflow_dispatch es el evento de GitHub Actions para iniciar un workflow bajo demanda. En la interfaz aparece como Run workflow; desde una terminal se invoca con gh workflow run. Es útil para tareas que necesitan una decisión explícita: ejecutar una migración en modo de prueba, reconstruir un índice, sembrar datos de staging o preparar un despliegue que todavía pasará por controles de Environment.

No es un reemplazo de la integración continua de cada pull request ni un cron escondido. El archivo YAML sigue definiendo permisos, inputs, rama, entorno y pasos. Para un coding agent, esa separación importa: la acción irreversible debe conservar un control humano o una política equivalente.

Esta guía se verificó el 3 de septiembre de 2026 contra la documentación oficial de eventos de GitHub Actions y el manual de GitHub CLI. GitHub especifica que el workflow debe existir en la rama predeterminada para que el evento manual esté disponible.

Cuándo sí conviene usar workflow_dispatch

El mejor caso es una tarea válida pero poco frecuente, donde ejecutarla en cada push sería cara o peligrosa. Por ejemplo:

• regenerar un catálogo después de revisar los datos de entrada;
• lanzar pruebas de carga contra un entorno elegido;
• repetir una importación con un identificador concreto;
• preparar un release con dry_run activado;
• ejecutar mantenimiento de staging sin abrir una sesión en el servidor.

Si la tarea debe ocurrir con cada commit, usa push o pull_request. Si debe ocurrir a una hora fija, usa schedule. Si otro workflow reutiliza la misma lógica, considera workflow_call. Elegir el evento correcto hace visible la intención y evita que un agente “simule” automatización disparando manualmente el mismo job cada pocos minutos.

Consulta también concurrency para GitHub Actions si dos ejecuciones simultáneas podrían competir, y timeout-minutes para que una operación atascada no consuma el límite máximo del runner.

Un workflow mínimo con defaults seguros

Este ejemplo recibe un modo de ejecución y un destino. El valor inicial no escribe y el entorno se limita a opciones conocidas:

name: Mantenimiento bajo demanda

on:
  workflow_dispatch:
    inputs:
      dry_run:
        description: "Simular sin escribir cambios"
        required: true
        type: boolean
        default: true
      target:
        description: "Entorno de destino"
        required: true
        type: choice
        options:
          - staging
          - production
        default: staging

permissions:
  contents: read

jobs:
  maintain:
    runs-on: ubuntu-latest
    environment: ${{ inputs.target }}
    steps:
      - uses: actions/checkout@v4
      - name: Ejecutar mantenimiento
        env:
          DRY_RUN: ${{ inputs.dry_run }}
          TARGET: ${{ inputs.target }}
        run: ./scripts/maintain.sh

El input booleano conserva su tipo en el contexto inputs. GitHub aclara que github.event.inputs también contiene los valores, pero convierte los booleanos a texto; por eso conviene leer inputs.dry_run cuando una condición necesita un booleano real. Un input choice resuelve a una cadena, pero evita valores arbitrarios como prodction o el nombre inesperado de otro entorno.

permissions: contents: read aplica mínimo privilegio al token automático. Si un paso necesita escribir, concede solo el permiso requerido al job correspondiente. Para producción, asocia el job con un GitHub Environment que tenga las protecciones apropiadas; el input no sustituye esas reglas.

Cómo dispararlo desde la interfaz y desde gh

Cuando el archivo existe en la rama predeterminada, Actions muestra Run workflow. Allí se elige la referencia y se completan los inputs requeridos. La documentación oficial indica que, después de que el workflow haya corrido al menos una vez, también puede despacharse contra otra rama o tag por API o GitHub CLI.

Desde terminal:

gh workflow run maintain.yml \
  --ref main \
  -f dry_run=true \
  -f target=staging

--ref elimina ambigüedad sobre la versión del YAML y del código que se ejecutará. -f o --raw-field envía pares clave=valor; el manual también permite JSON por entrada estándar. Después del disparo, observa el run en vez de asumir que terminó bien:

gh run list --workflow maintain.yml --limit 5
gh run watch <run-id> --exit-status

Un agente debe registrar el workflow, la referencia, los inputs no secretos y la URL del run. Nunca debe imprimir tokens ni valores sensibles en su reporte. Si el comando no devuelve una URL inmediatamente, consulta la lista de runs y correlaciona por workflow, rama y hora.

Contrato operativo para coding agents

Antes de permitir que un agente ejecute gh workflow run, define un contrato corto y comprobable:

1. Allowlist de workflows. El agente solo puede disparar archivos aprobados; no selecciona cualquier YAML encontrado en el repositorio.
2. Referencia explícita. Pasa --ref y verifica que el commit esperado esté publicado en el remoto.
3. Default reversible. dry_run=true, target=staging o equivalente debe ser el camino normal.
4. Producción protegida. Un Environment, reviewer requerido u otra política debe detener la escritura irreversible.
5. Inputs sin secretos. Los identificadores sensibles se obtienen desde secrets o mecanismos de identidad de corta duración, no desde el prompt.
6. Seguimiento real. El agente espera la conclusión y reporta éxito, fallo o cancelación con evidencia.
7. Reintentos deliberados. Un fallo no autoriza a disparar múltiples runs en paralelo.

Puedes copiar este bloque a AGENTS.md:

Use workflow_dispatch only for allowlisted on-demand workflows.
Always pass an explicit ref and safe inputs.
Default to dry-run or staging.
Never dispatch production without its required approval gate.
Watch the resulting run and report its final conclusion.
Do not place secrets in workflow inputs or logs.

Este contrato complementa GitHub CLI para PRs: abrir un PR y ejecutar una tarea operativa son capacidades distintas. El permiso para una no implica permiso para la otra.

Errores frecuentes y cómo corregirlos

Error	Riesgo	Corrección
Usar workflow_dispatch como cron	Runs manuales repetidos y sin cadencia declarada	Usa schedule y documenta la zona horaria
target como texto libre	Destinos inválidos o inesperados	Usa choice o environment
Omitir --ref	Ejecutar otra versión del workflow	Fija rama o tag deliberadamente
dry_run inicia en false	El primer clic escribe cambios	Default seguro y paso de confirmación
Token con permisos amplios	Mayor impacto si un paso se compromete	Declara permisos mínimos por workflow o job
No observar la conclusión	Reportar éxito solo porque se creó el run	gh run watch --exit-status y revisar logs
Inputs con secretos	Exposición accidental en evento o logs	Usa secrets, OIDC o credenciales efímeras

No mezcles pull_request_target con esta solución. Responde a actividad de un PR y tiene consideraciones especiales con código no confiable; workflow_dispatch representa una decisión manual. Para lógica reutilizable, workflow_call expresa mejor esa intención.

Checklist antes de autorizar un run

• El archivo del workflow existe en la rama predeterminada.
• El workflow está en una allowlist operativa.
• La referencia apunta al commit esperado.
• Los inputs son tipados y el default es reversible.
• Ningún secreto viaja como input o argumento visible.
• Los permisos de GITHUB_TOKEN son mínimos.
• Producción usa un Environment o una aprobación equivalente.
• concurrency impide operaciones incompatibles en paralelo.
• timeout-minutes limita jobs atascados.
• El agente observará y reportará la conclusión del run.

Preguntas frecuentes

¿Por qué no aparece el botón Run workflow? El evento debe estar declarado y el archivo debe existir en la rama predeterminada. Verifica también que Actions esté habilitado para el repositorio.

¿Puedo ejecutar el workflow contra una rama distinta? Sí. GitHub documenta que, una vez que el workflow ha corrido al menos una vez, la API o CLI puede despacharlo contra una rama o tag. Pasa --ref de forma explícita.

¿Debo usar inputs o github.event.inputs? Prefiere inputs para condiciones: conserva booleanos como booleanos. github.event.inputs convierte esos valores a cadenas.

¿gh workflow run necesita guardar un PAT en el repositorio? No. Usa la autenticación de GitHub CLI en el entorno que dispara el evento. Dentro del workflow, limita GITHUB_TOKEN; para cloud, considera identidad federada cuando el proveedor la soporte.

¿Un agente puede desplegar producción con este evento? Técnicamente puede iniciar un run si tiene permisos, pero eso no significa que deba saltarse controles. Mantén la aprobación de Environment o una política explícita para el paso irreversible.

Para aprender a separar ejecución, revisión y publicación, sigue el hub de seguridad, coste y operación y el curso gratuito para instalar un agente. workflow_dispatch funciona mejor como puerta visible y auditable, no como atajo silencioso a producción.