Saltar al contenido

¿Qué es workflow_dispatch en GitHub Actions?

Última actualización

workflow_dispatch es un disparador de GitHub Actions que le permite iniciar un workflow manualmente, desde la pestaña Actions, la GitHub CLI o la API REST, opcionalmente pasando inputs con tipo.

Cómo funciona

Añada workflow_dispatch bajo on: y, si desea parámetros, declare inputs. GitHub mostrará entonces un botón "Run workflow" en la pestaña Actions de ese workflow, con un selector de rama y un formulario para los inputs. Dentro del workflow, lea los valores desde github.event.inputs o desde el contexto inputs.

Los tipos de input son string, boolean, choice, number y environment. Un input de tipo choice necesita una lista options. Puede marcar los inputs como required y asignarles un default.

El archivo del workflow debe existir en la rama predeterminada para que aparezca el botón, aunque después puede ejecutarlo contra otra rama.

Ejemplo

on:
  workflow_dispatch:
    inputs:
      environment:
        description: Where to deploy
        type: choice
        options: [staging, production]
        default: staging
      dry_run:
        description: Skip the real deploy
        type: boolean
        default: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Deploying to ${{ inputs.environment }} (dry run: ${{ inputs.dry_run }})"

Inícielo desde una terminal:

gh workflow run deploy.yml -f environment=staging -f dry_run=false

Usos habituales

  • Despliegues y rollbacks con un solo clic.
  • Reejecución de backfills de datos o scripts de mantenimiento.
  • Ejecuciones de benchmark o pruebas de carga bajo demanda.
  • Probar un trabajo programado sin esperar a la hora del cron. Consulte programaciones cron.

Errores comunes

  • Workflow que no está en la rama predeterminada. El botón Run workflow no aparecerá hasta que se fusione el archivo.
  • Inputs booleanos comparados como cadenas. Con el contexto github.event.inputs, más antiguo, los booleanos llegan como cadenas. Prefiera el contexto inputs, que conserva los tipos.
  • Demasiados inputs. La API limita el número de inputs, y los formularios largos favorecen los errores. Use valores predeterminados razonables.
  • Sin protección en despliegues a producción. Cualquier persona con acceso de escritura puede lanzar el disparador. Combínelo con reglas de protección de entornos.
  • Despliegues manuales en paralelo que compiten. Dos despliegues manuales a la vez pueden chocar. Use un grupo de concurrencia.

workflow_dispatch es también la forma habitual de probar un workflow reutilizable durante el desarrollo, junto con workflow_call.

Preguntas frecuentes

¿Se puede combinar workflow_dispatch con otros disparadores?

Sí. Un workflow puede incluir push, pull_request, schedule y workflow_dispatch a la vez. Los inputs solo se establecen en las ejecuciones manuales.

¿Cuál es la diferencia entre workflow_dispatch y repository_dispatch?

workflow_dispatch apunta a un workflow concreto. repository_dispatch envía un evento personalizado al repositorio, y se ejecuta cualquier workflow que escuche ese tipo de evento.

¿Quién puede activarlo?

Las personas con acceso de escritura al repositorio, o los tokens con los permisos adecuados.