GitHub Action: return-dispatch

Dispatch an action to a foreign repository and output the newly created run ID.

The returned run ID can be used to await the completion of the remote run using await-remote-run.

Usage

The dispatched workflow needs no special setup. It only has to accept the workflow_dispatch event and declare any inputs you pass via workflow_inputs.

steps:
- name: Dispatch an action and get the run ID and URLuses: codex-/return-dispatch@v4id: return_dispatchwith:
token: ${{ secrets.TOKEN }} # Note this is NOT GITHUB_TOKEN but a PATref: target_branch # or refs/heads/target_branchrepo: repository-nameowner: repository-ownerworkflow: automation-test.ymlworkflow_inputs: '{ "some_input": "value" }'# Optional
- name: Use the output run ID and URLrun: | echo ${{steps.return_dispatch.outputs.run_id}} echo ${{steps.return_dispatch.outputs.run_url}} - name: Await Run ID ${{ steps.return_dispatch.outputs.run_id }}uses: Codex-/await-remote-run@v2with:
token: ${{ github.token }}repo: repository-nameowner: repository-ownerrun_id: ${{ steps.return_dispatch.outputs.run_id }}

Token

GITHUB_TOKEN can only access the repository containing the workflow, so dispatching to another repository requires a Personal Access Token (PAT). Dispatching within the same repository works with GITHUB_TOKEN, provided it is granted actions: write.

Permissions Required

One of the following, depending on the token type:

• Fine-grained PAT, GitHub App, or GITHUB_TOKEN: Actions repository permission, write
• Classic PAT or OAuth token: repo scope

APIs Used

• Create a workflow dispatch event
  • POST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches
  • Sent with return_run_details: true, so the response carries the new run's ID and URL
  • Requires github.com or GitHub Enterprise Server 3.21+, older servers cannot return the run details

For more information please see api.ts.

Where does this help?

If you have an action in a repository that dispatches an action on a foreign repository, you need to know which foreign run you've just dispatched before you can wait for it or poll it for a completion status (success, failure, etc).

This Action gets you that run ID and URL as step outputs, so you can hand them straight to something like await-remote-run.