GitHub Actions: Workflow Dispatch API ahora devuelve Run IDs

Introducción

GitHub ha actualizado el endpoint de Workflow Dispatch API de GitHub Actions para facilitar la correlación entre una llamada API y la ejecución de workflow que se crea como resultado.

Hasta ahora, al lanzar un workflow mediante el endpoint de dispatch, la respuesta correcta era un 204 No Content. Ese comportamiento confirmaba que la petición había sido aceptada, pero no devolvía información directa sobre la ejecución creada. En integraciones externas, esto obligaba a hacer consultas posteriores al historial de runs, filtrar por rama, evento, hora o inputs, y construir lógica adicional para identificar el run correcto.

Con la nueva opción return_run_details, el endpoint puede devolver una respuesta 200 OK con metadatos de la ejecución asociada, incluyendo información útil para localizarla desde la API o desde la interfaz de GitHub.

Qué cambia en Workflow Dispatch API

El endpoint afectado es:

POST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches

Este endpoint permite iniciar un workflow que tenga habilitado el evento workflow_dispatch.

El cambio principal es el siguiente:

• Si no se envía el nuevo parámetro opcional, el comportamiento se mantiene: la API responde 204 No Content.
• Si se envía return_run_details con valor true, la API puede responder 200 OK e incluir metadatos que permiten relacionar la petición con el workflow run creado.
• GitHub CLI también incorpora soporte para este comportamiento a partir de la versión v2.87.0.

La mejora es especialmente relevante para sistemas que disparan workflows desde fuera de GitHub y necesitan registrar, auditar o monitorizar la ejecución resultante.

Por qué es importante disponer del Run ID

El identificador de una ejecución de GitHub Actions permite trabajar con un run concreto, no solo con el workflow en abstracto. En la práctica, esto ayuda a:

• Trazabilidad: asociar una petición externa con la ejecución exacta creada en GitHub Actions.
• Auditoría: registrar qué sistema disparó un workflow, cuándo lo hizo y qué run se generó.
• Monitorización: consultar el estado de una ejecución concreta sin tener que inferirla a partir del historial.
• Integraciones externas: guardar la URL o identificador del run en sistemas como Azure DevOps, Azure Functions, Logic Apps, ITSM, CMDBs o herramientas internas.
• Depuración: acceder más rápido a logs, jobs y resultados de la ejecución.

Antes de esta actualización, era habitual implementar polling sobre la lista de runs del workflow y aplicar filtros por ref, evento, fecha de creación o inputs. Ese enfoque funcionaba, pero podía ser frágil en repositorios con muchas ejecuciones concurrentes.

Uso básico del nuevo parámetro

Un workflow debe estar preparado para ser lanzado bajo demanda mediante workflow_dispatch. Por ejemplo:

name: Deploy

on:
  workflow_dispatch:
    inputs:
      environment:
        description: "Entorno de destino"
        required: true
        type: choice
        options:
          - dev
          - prod

Una llamada al endpoint de dispatch puede incluir el nuevo parámetro opcional return_run_details.

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.github.com/repos/OWNER/REPO/actions/workflows/deploy.yml/dispatches" \
  -d '{
    "ref": "main",
    "inputs": {
      "environment": "dev"
    },
    "return_run_details": true
  }'

Conviene tratar la respuesta de forma explícita:

• 200 OK: la API devuelve metadatos de la ejecución creada.
• 204 No Content: comportamiento clásico del endpoint cuando no se solicita la devolución de detalles.
• Otros códigos: error de permisos, workflow inexistente, rama no válida, inputs incorrectos o restricciones de la organización/repositorio.

Ejemplo de consumo desde Python

El siguiente ejemplo evita depender de cabeceras no documentadas y diferencia el comportamiento antiguo del nuevo:

import json
import os

import requests

GITHUB_TOKEN = os.environ["GITHUB_TOKEN"]
OWNER = "mi-organizacion"
REPO = "mi-repositorio"
WORKFLOW_ID = "deploy.yml"

url = (
    f"https://api.github.com/repos/{OWNER}/{REPO}"
    f"/actions/workflows/{WORKFLOW_ID}/dispatches"
)

payload = {
    "ref": "main",
    "inputs": {
        "environment": "dev"
    },
    "return_run_details": True
}

headers = {
    "Accept": "application/vnd.github+json",
    "Authorization": f"Bearer {GITHUB_TOKEN}"
}

response = requests.post(url, headers=headers, json=payload, timeout=30)

if response.status_code == 200:
    run_details = response.json()
    print("Workflow lanzado. Metadatos devueltos por la API:")
    print(json.dumps(run_details, indent=2))

elif response.status_code == 204:
    print(
        "Workflow lanzado correctamente, pero la respuesta no incluye detalles. "
        "Comprueba que return_run_details esté habilitado en la solicitud."
    )

else:
    print(f"Error al lanzar el workflow: {response.status_code}")
    print(response.text)
    response.raise_for_status()

El punto importante es que el código debe contemplar ambos comportamientos. En integraciones existentes, GitHub mantiene la respuesta 204 No Content si no se usa el nuevo parámetro.

Permisos y configuración a revisar

Para que la llamada funcione correctamente, hay varios aspectos que conviene validar:

1. El workflow debe declarar workflow_dispatch
   Si el workflow no admite ejecución manual o por API, el endpoint no podrá lanzarlo.

2. La referencia debe existir
   El valor de ref debe apuntar a una rama o tag válido donde exista el workflow.

3. Los inputs deben coincidir con el workflow
   Si el workflow define inputs obligatorios, deben enviarse en la petición.

4. El token debe tener permisos suficientes
   El token utilizado debe estar autorizado para ejecutar workflows en el repositorio. En organizaciones con políticas restrictivas, también pueden influir reglas de seguridad, permisos de Actions y configuración de tokens.

5. No asumir cabeceras no documentadas
   El cambio anunciado por GitHub se basa en devolver metadatos en la respuesta cuando se solicita return_run_details. No conviene depender de cabeceras personalizadas si no están documentadas oficialmente para este caso.

Soporte en GitHub CLI

GitHub también ha incorporado soporte en GitHub CLI a partir de la versión v2.87.0.

Al ejecutar un workflow con:

gh workflow run deploy.yml --ref main -f environment=dev

la CLI puede devolver la URL de la ejecución creada y un comando gh run view para consultarla. Esto simplifica el uso interactivo y también ayuda en scripts donde se quiera mostrar al operador un enlace directo al run.

En equipos que usan automatización basada en CLI, es recomendable validar la versión instalada:

gh --version

Si el comportamiento esperado no aparece, conviene actualizar la CLI a una versión compatible.

Casos de uso en arquitecturas Azure

Aunque la funcionalidad pertenece a GitHub Actions, tiene impacto directo en arquitecturas donde Azure actúa como plataforma de ejecución, integración u observabilidad.

1. Orquestación desde Azure Functions o Logic Apps

Una Azure Function o una Logic App puede disparar un workflow de GitHub Actions mediante la API y almacenar los metadatos devueltos en:

• Application Insights.
• Azure Storage.
• Azure Table Storage.
• Cosmos DB.
• Un sistema interno de auditoría.

De esta forma, cada petición de negocio puede quedar asociada al run concreto de GitHub Actions que ejecutó la automatización.

2. Integración con Azure DevOps

En organizaciones que combinan Azure DevOps y GitHub Actions, el Run ID o la URL del run pueden usarse como referencia cruzada entre sistemas.

Por ejemplo:

• Un pipeline de Azure DevOps dispara un workflow de GitHub Actions.
• La respuesta del dispatch se registra como variable o artefacto del pipeline.
• El operador puede navegar desde Azure DevOps al run concreto en GitHub Actions.

La clave es evitar correlaciones aproximadas basadas solo en timestamps o nombres de rama.

3. Despliegues en Azure App Service o AKS

En despliegues hacia Azure App Service, Azure Kubernetes Service o Azure Container Apps, disponer del identificador o URL del run permite registrar qué ejecución produjo un despliegue determinado.

Algunos usos prácticos:

• Incluir la URL del run en anotaciones de despliegue.
• Guardar el identificador del run junto al número de versión de la aplicación.
• Asociar imágenes de contenedor con la ejecución que las construyó.
• Mejorar la trazabilidad ante incidentes o rollbacks.

4. Auditoría y cumplimiento

En entornos regulados, una traza completa suele requerir responder preguntas como:

• ¿Quién o qué sistema inició el despliegue?
• ¿Qué workflow se ejecutó?
• ¿Qué commit o rama se usó?
• ¿Dónde están los logs de la ejecución?
• ¿Qué resultado tuvo el proceso?

La devolución de metadatos en el dispatch reduce la cantidad de lógica personalizada necesaria para reconstruir esa relación.

Recomendaciones de implementación

Para adoptar esta mejora de forma segura:

• Añade return_run_details solo en integraciones donde necesites correlación directa.
• Mantén compatibilidad con respuestas 204 No Content si tienes scripts usados en varios repositorios o entornos.
• Registra la URL o identificador de la ejecución en tu sistema de observabilidad.
• Evita hacer parsing de URLs si la respuesta ya ofrece campos estructurados.
• Revisa los permisos del token y usa el principio de mínimo privilegio.
• En scripts con GitHub CLI, valida que la versión sea v2.87.0 o superior.

Limitaciones y consideraciones

Esta mejora no elimina todas las necesidades de seguimiento. En muchos casos, después de obtener los metadatos iniciales del run, seguirás necesitando consultar la API de GitHub Actions para conocer:

• Estado de la ejecución.
• Conclusión final.
• Jobs asociados.
• Logs.
• Artefactos generados.

Además, en automatizaciones críticas, es recomendable contemplar reintentos, timeouts y errores intermedios. Que el dispatch devuelva metadatos no significa que el workflow haya terminado correctamente; solo facilita identificar la ejecución creada.

Conclusión

La incorporación de return_run_details en Workflow Dispatch API corrige una limitación habitual de GitHub Actions: la dificultad de asociar de forma directa una llamada API con el workflow run resultante.

El cambio mantiene compatibilidad con el comportamiento anterior (204 No Content) y añade una vía más limpia para obtener metadatos cuando se necesitan. Para equipos que integran GitHub Actions con Azure, plataformas internas u otros sistemas de orquestación, esta mejora reduce polling, simplifica auditoría y mejora la trazabilidad operativa.

Fuente oficial

• GitHub Changelog: Workflow dispatch API now returns run IDs