Platform engineering lives and dies by small pieces of API ergonomics. A missing ID means a new polling loop. A missing URL means someone screenscrapes a UI. And those small frictions compound into brittle automation, flaky ChatOps bots, and internal portals that “work most of the time.”
That’s why a recent GitHub change is worth paying attention to: the workflow dispatch API can now return run IDs and related details when you trigger a workflow. Historically, the API returned a 204 No Content response — which forced callers to implement out-of-band discovery to figure out which run corresponded to their dispatch request.
This post explains what changed, why it matters, and how to take advantage of it in real platform workflows.
The old world: “fire and hope” + expensive polling
Workflow dispatch is a core building block for internal automation. Common uses include:
- Environment provisioning (“create me a staging environment”)
- Deploy requests (“deploy version X to prod”)
- Backfills (“reprocess last 24 hours of data”)
- Security workflows (“rotate secrets”, “invalidate tokens”)
In all of these, the caller typically needs three things immediately:
- A unique identifier to track progress
- A URL to show humans the status
- A handle to attach logs/artifacts/notifications
When the API returned no content, teams resorted to hacks:
- Poll the list of recent runs and guess which one is “yours”
- Encode a correlation ID into workflow inputs, then search logs
- Build a shadow database that reconciles dispatch requests to runs
These approaches are fragile, especially when runs are frequent and parallel. If multiple dispatches happen close together, correlation can break. If the GitHub UI changes, scraping breaks. If a run is queued, you can’t tell whether it exists yet.
The new capability: return run details directly
GitHub’s update adds an optional boolean parameter, return_run_details, to the workflow dispatch API. When set, the endpoint returns a 200 OK response containing details like:
- workflow ID
- API URL
- workflow URL
GitHub also notes that the GitHub CLI supports this behavior, and new CLI versions default to returning the URL of the created run. That matters because many platform teams standardize on gh inside automation containers, especially for self-service operations.
Why this matters for platform engineering (beyond “nice to have”)
Returning run details turns workflow dispatch into a more reliable primitive for higher-level platform UX.
1) Better ChatOps: instant links, not “I’ll update you later”
If your bot triggers a workflow from Slack/Teams/WhatsApp, you can immediately reply with a run URL. Humans trust systems that give them a concrete artifact to click, especially during incidents.
2) Internal developer portals can behave like real product UIs
Developer portals (Backstage and others) often wrap Actions workflows for golden-path automation. With run IDs/URLs, portals can show a job timeline, embed logs, and store stable references without guesswork.
3) Less waste: polling reduction is cost reduction
Polling the Actions API is not free. At scale, it becomes a rate-limiting and operational concern. A single response containing the tracking handle reduces pressure on GitHub APIs and on your own automation infrastructure.
4) Cleaner incident forensics
When something goes wrong, you want to trace “who requested this” to “what exactly ran.” A run ID makes audit trails and postmortems more deterministic.
Implementation guidance: adopting safely
A few recommendations when you start using the new response mode:
- Store the run URL in your system of record. Don’t only stream it to chat; persist it with the request ticket or portal action record.
- Keep correlation IDs anyway. A run ID is great, but also pass a request ID into workflow inputs so logs and artifacts remain searchable across systems.
- Handle queuing states. Some workflows will not start immediately. Build UI states for queued/in-progress/succeeded/failed.
- Don’t over-privilege tokens. If your automation now relies more heavily on run metadata, confirm that tokens only need read-only access to fetch status and logs.
What this signals: GitHub is smoothing the “automation API” surface
Over the last few years, GitHub Actions has evolved from “CI/CD for code” into a general automation plane for engineering organizations. That requires better primitives: stable IDs, idempotency patterns, and traceability features.
This change is a small but meaningful step in that direction — and it’s the kind of improvement that platform teams should adopt quickly because it removes complexity you never wanted to own.
Leave a Reply