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 and URL
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 and URL
run: |
echo ${{steps.return_dispatch.outputs.run_id}}
echo ${{steps.return_dispatch.outputs.run_url}}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:
reposcope- You may get away with simply having
repo:public_repo repois definitely needed if the repository is private.
- You may get away with simply having
actions:readactions: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:
repoactions:write
- POST
- List repository workflows
- GET
/repos/{owner}/{repo}/actions/workflows - Permissions:
repoactions: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:
repoactions: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 │
└──────┘ └───────────────┘
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
![renovate[bot] avatar](https://avatars.githubusercontent.com/in/2740?v=4 "renovate[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent