The dispatches API should return the run ID

[neilmayhew]

The Create a workflow dispatch event returns empty content. However, this makes it very difficult to track the workflow that was triggered because getting its ID is inherently 'racy'. The triggered workflow may have finished before you can check for it, or another job may already be running. It would be much better if the API returned the ID of the workflow that was dispatched.

This is an ongoing problem in the convictional/trigger-workflow-and-wait action that's available in the Marketplace, and there's currently a PR open that's trying to fix this, but it's going to be very difficult to make it robust.

Update: I wrote a better PR and it was merged. The finished code now has a robust mechanism for getting the run ID.

[chrispat]

Thank you for your feedback.

We are aware of this issue, however, at the moment there are some technical challenges with providing this information. Under the covers the workflow_dispatch is a webhook just like all of the other events that trigger Actions workflows. This means it is processed asynchronously and at the time of API call we simply don't know the run id so we can't return it.

It is something the team is aware of and hope to address in the future.

[BrianOpteran]

This is madness. It's basic API design. You can still be asynchronous with the webhook - return a UUID for this request and call that the dispatch_uuid. The UUID is attached to the payload that is part of the slower tasks. This UUID is attached to the workflow run information as dispatch_uuid...

[jebeaudet]

2+ years since this has been reported and no progress, this is really necessary for any kind of 3rd party integration launching and monitoring workflow in Github. Is there any news on this?

[keplerk]

Or at least if there was a way to send an identifier as part of the payload and have the way to search by that identifier would help as well, in that way it won't matter if it's async or not because the info will be part of the inputs.

[neilmayhew]

I unmarked this as "answered" because it's been 2y and there still isn't a real solution, only clunky workarounds.

[benc-uk]

This is API design 101 for any asynchronous task or API, amazing this made it to production in this state

[neilmayhew]

In case anyone finds this discussion and is looking for a workaround, I've implemented one in a new PR. The idea is to compare the lists of run IDs before and after the trigger API is called. However, we don't need to fetch the full history of run IDs, only those since a couple of minutes before the trigger, and thankfully the runs API allows you to filter by time.

[aranair]

Is there a way to maybe expose a specific input from dispatched workflows (e.g. some id generated client-side and passed in when triggering)? We can then query using that, for the exact run-id via the api at a later time, when it is available? (or at the very least be able to "de-race" by inspecting that field for runs that happen at the same time)

All that's needed would be to add some whitelisted fields for this in the API?

[jdbodyfelt]

Can we please get a return run_ID or job_ID array for the dispatch? It's lack is making completion polling and logging a real PitA.

[neilmayhew]

I recommend you use the convictional/trigger-workflow-and-wait action:

- name: Example
  uses: convictional/[email protected]
  with:
    owner: my-org
    repo: other-repo
    workflow_file_name: other-workflow.yaml
    github_token: ${{ secrets.GH_TOKEN }}
    client_payload: '{"key1": "value1", "key2": "value2"}'

This takes care of waiting for the other job and returning a success or failure according to whether the other workflow succeeded or failed.

[xvzf]

So I solved this by injecting a non-used input field and search for it again when retrieving the workflows. This is a very much needed feature imho

[skuriyadi]

Please provide an example.
Thank you

[gusostow]

Does the workflow runs API return the input values?

[benbuckman]

I happen to be encountering the same issue now, and I'm not seeing where the raw inputs are returned in the workflow runs API. ☝️
Thanks

[ebracho]

Alternative approach:

1. Create a temporary branch ref for the commit sha (e.g. tmp-${UUID}) and trigger the workflow on it
2. Poll for workflow runs with branch=tmp-${UUID}
3. Delete the branch once you retrieve the workflow run

This way you don't have to worry about other workflow runs triggering on the same ref.

[lasith-kg]

Affilitiation: I acknowledge that I am a major contributor to this GitHub Action.

lasith-kg/dispatch-workflow@v1 is a GitHub Action that dispatches workflows either using repository_dispatch or workflow_dispatch event and has an optional flag discover: true. When this flag is enabled, it injects a unique UUID into the Workflow Run Name so that it can be correlated to the initial dispatch event. Once the workflow is discovered, the Run ID and Run URL is available from the step outputs.

steps:
  - uses: lasith-kg/dispatch-workflow@v1
    id: dispatch-with-discovery
    name: "Dispatch Workflow With Discovery"
    with:
      dispacth-method: workflow_dispatch | repository_dispatch
      ...
      discover: true
  - id: echo-run-id-url
    name: "Echo Run ID and Run URL"
    run: |
      echo "${{ steps.dispatch-with-discovery.outputs.run-id }}"
      echo "${{ steps.dispatch-with-discovery.outputs.run-url }}"

Naturally, the receiving workflow needs to be modified to intercept this UUID in the run-name

workflow_dispatch

name: Receiving Workflow
run-name: Receiving Workflow [${{ inputs.distinct_id && inputs.distinct_id || 'N/A' }}]

on:
  workflow_dispatch:
    inputs:
      distinct_id:
        description: 'Distinct ID'
        required: false

repository_dispatch

name: Receiving Workflow
run-name: >
  Receiving Workflow [${{
    github.event.client_payload.distinct_id &&
    github.event.client_payload.distinct_id || 'N/A' }}]

on:
  repository_dispatch:
    types:
      - deploy

[jdbodyfelt]

Perfect! Thank you!

[haolingdong-msft]

Provide an alternative solution I use：
Add an input parameter we call UUID to your workflow configuration yaml file, then set run-name to include UUID.

run-name: Receiving Workflow [${{ inputs.UUID }}]

Then you can filter using run-name by the UUID when List workflow runs for a workflow. This call will return run name, then you just filter the matched run instance by the run-name.
Note: list-workflow-runs-for-a-workflow supports pass in create as query parameter to filter requests, if you found get all runs is too time-costing, you can add the filter to only inlucde a time period run instances.

[jstafford5380]

For what it’s worth, Jenkins addresses this by issuing a “queue id” at the time of the dispatch request. I imagine they simply generate and id and queue the dispatch. The id is passed back to the caller and then when the job starts, the build record (or workflow in the this case) will now have that id it as a property. Then the developer can query for recent build history for the particular job by name and then client side filter for the one with the id they were given and keep polling until the status comes back indicating the run is complete. Architecturally, it’s pretty straight forward, but I don’t know what the scheduling infra looks like on the GHA side

[lkfortuna]

Hey there 👋 To provide an update here, we do not have this on our prioritized list for this year but have it on the list for next year. We do not have the funding to go after everything we want to fix, and we appreciate your patience on the delay.

I apologize I was wrong, we are work on fixing this this quarter, standby for more news on this!

[Brend-Smits]

Hi @lkfortuna,

Would you be able to provide an update on this please? No update is also an update!
Thank you 👍🏼

[owattley-rotageek]

I know this is not any individual engineers fault and I do not wish to admonish people who are just doing their job, so I guess my ire is directed broadly at Microsoft/Github as a whole here...

I cannot believe what I am reading in this thread after facing this issue for the first time today. It must surely be a joke that a multi-billion dollar company can't even output the most fundamental piece of information an API consumer would require to warrant using the API in the first place.

Why build the API if it cannot be reliably used? It's like building a car but you forgot the brakes and steering wheel. Guess we'll have to rely on the public to stop and steer that car.

I am trying to run and monitor a workflow from outside Github, so using an existing GH Action workaround is not viable for my use case - but thanks to the community for building these.

It looks like the only truly reliable way of doing it without any changes to your workflow (e.g. adding inputs) is to create a temporary unique ref branched off your main branch as per this comment. But this is so horrible. Nobody should need to be using this or any other workaround for what is essentially very basic data being returned in an API call.

Github, this issue was raised in 2022 and here we are in 2025. This is shamefully bad, please fix it.

[gm-k2v]

A year later and nothing still!?

[benc-uk]

Over three years and counting

[neilmayhew]

I am trying to run and monitor a workflow from outside Github, so using an existing GH Action workaround is not viable for my use case - but thanks to the community for building these.

@owattley-rotageek The "finished code" linked to in my update to the original post can be used from anywhere. It's just bash code. Although it's part of an existing action, it doesn't use any features of the actions environment. It works reliably without any ugly workarounds.

[neilmayhew]

To all who are complaining about this, there's a robust solution that doesn't involve any intrusive workarounds. Although it's currently in an existing action, it's just bash code and can be used from anywhere. (There's a link to it in my original post.)

It works by getting the list of currently running workflows before and after triggering the workflow, and seeing which are the new ones. Although there's a potential race condition if multiple external agents trigger the same workflow at the same time, it's fail-safe because the agents will just wait for all the new workflows to finish. Even though this isn't perfect, the race is unlikely to happen in practice.

The same logic could easily be written in another language, using the existing bash code as a guide.

[KoenWillemse]

It's a workaround that probably a lot of people are now using (me too), but I would not call it a robust solution.

[neilmayhew]

That's a fair comment. However, it's more robust than any of the previous non-intrusive solutions, and it seems to work well in practice. Have you experienced any problems with it?

[ataylorme]

I follow these steps:

1. Create a temporary branch with a unique ID
2. Trigger the workflow via dispatch event with the temporary branch as the source
3. Delete the temporary branch
4. Polling for the triggered workflow run using GET /repos/{owner}/{repo}/actions/runs, which accepts branch as a search parameter

Polling takes less than 30 seconds in most cases, with edge cases being a GitHub Actions incident where jobs don't start. The temporary branch is necessary to ensure you select the correct workflow run and will ever only get the single, correct result when polling.

[austinpray-mixpanel]

We have been using this approach for a couple years now https://github.com/orgs/community/discussions/9752#discussioncomment-5247573. GitHub's APIs for creating branches are somewhat flakey at scale. I wish I didn't have to do this.

[ataylorme]

I also wish we didn’t have to jump through these hoops