Dispatch an action to a foreign repository and output the newly created run ID.
This Action exists as a workaround for the issue where dispatching an action to foreign repository does not return any kind of identifier.
Ensure you have configured your remote action correctly, see below for an example.
steps:
- name: Dispatch an action and get the run ID
uses: codex-/return-dispatch@v1
id: return_dispatch
with:
token: ${{ secrets.TOKEN }} # Note this is NOT GITHUB_TOKEN but a PAT
ref: target_branch # or refs/heads/target_branch
repo: repository-name
owner: repository-owner
workflow: automation-test.yml
workflow_inputs: { "some_input": "value" } # Optional
workflow_timeout_seconds: 120 # Default: 300
- name: Use the output run ID
run: echo ${{steps.return_dispatch.outputs.run_id}}
In the earliest possible stage for the Action, add the input into the name.
As every step needs a uses
or run
, simply echo
the ID or similar to satisfy this requirement.
name: action-test
on:
workflow_dispatch:
inputs:
distinct_id:
jobs:
test:
runs-on: ubuntu-latest
steps:
- name: echo distinct ID ${{ github.event.inputs.distinct_id }}
run: echo ${{ github.event.inputs.distinct_id }}
To be able to use dispatch we need to use a token which has repo
permissions. GITHUB_TOKEN
currently does not allow adding permissions for repo
level permissions currently so a Personal Access Token (PAT) must be used.
The permissions required for this action to function correctly are:
repo
scope- You may get away with simply having
repo:public_repo
repo
is definitely needed if the repository is private.
- You may get away with simply having
actions:read
actions:write
For the sake of transparency please note that this action uses the following API calls:
- Create a workflow dispatch event
- POST
/repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches
- Permissions:
repo
actions:write
- POST
- List repository workflows
- GET
/repos/{owner}/{repo}/actions/workflows
- Permissions:
repo
actions:read
- GET
- List workflow runs
- GET
/repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs
- Permissions:
repo
- GET
- List jobs for a workflow run
- GET
/repos/{owner}/{repo}/actions/runs/{run_id}/jobs
- Permissions:
repo
actions:read
- GET
For more information please see api.ts.
If you have an action in a repository that dispatches an action on a foreign repository currently with Github API there is no way to know what the foreign run you've just dispatched is. Identifying this can be cumbersome and tricky.
The consequence of not being provided with something to identify the run is that you cannot easily wait for this run or poll the run for it's completion status (success, failure, etc).
┌─────────────────┐
│ │
│ Dispatch Action │
│ │
│ with unique ID │
│ │
└───────┬─────────┘
│
│
▼ ┌───────────────┐
┌────────────────┐ │ │
│ │ │ Request steps │
│ Request top 10 ├────────────────►│ │
│ │ │ for each run │
│ workflow runs │ │ │
│ │◄────────────────┤ and search │
└───────┬────────┘ Retry │ │
│ └───────┬───────┘
│ │
Timeout │ │
│ │
▼ ▼
┌──────┐ ┌───────────────┐
│ Fail │ │ Output run ID │
└──────┘ └───────────────┘