https://github.com/codex-/return-dispatch
⚙️ Dispatch an action to a foreign repository and output the newly created run ID.
https://github.com/codex-/return-dispatch
actions dispatch github-actions workflow
Last synced: 10 months ago
JSON representation
⚙️ Dispatch an action to a foreign repository and output the newly created run ID.
- Host: GitHub
- URL: https://github.com/codex-/return-dispatch
- Owner: Codex-
- License: mit
- Created: 2021-07-19T00:23:53.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-05-03T22:02:13.000Z (over 1 year ago)
- Last Synced: 2024-05-03T23:22:01.536Z (over 1 year ago)
- Topics: actions, dispatch, github-actions, workflow
- Language: TypeScript
- Homepage:
- Size: 3.63 MB
- Stars: 32
- Watchers: 3
- Forks: 10
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# GitHub Action: return-dispatch
[](https://github.com/Codex-/return-dispatch/actions/workflows/test.yml) [](https://github.com/prettier/prettier) [](https://codecov.io/gh/Codex-/return-dispatch) [](https://github.com/marketplace/actions/return-dispatch)
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.
## Usage
Ensure you have configured your remote action correctly, see below for an example.
### Dispatching Repository Action
```yaml
steps:
- name: Dispatch an action and get the run ID and URL
uses: codex-/return-dispatch@v2
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
workflow_job_steps_retry_seconds:
# Lineal backoff retry attempts are made where the attempt count is
# the magnitude and the scaling value is `workflow_job_steps_retry_seconds`
10 # Default: 5
distinct_id: someDistinctId # Optional
- name: Use the output run ID and URL
run: |
echo ${{steps.return_dispatch.outputs.run_id}}
echo ${{steps.return_dispatch.outputs.run_url}}
```
### Receiving Repository Action
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.
```yaml
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 }}
```
## Token
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.
### Permissions Required
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.
- `actions:read`
- `actions:write`
### APIs Used
For the sake of transparency please note that this action uses the following API calls:
- [Create a workflow dispatch event](https://docs.github.com/en/rest/actions/workflows#create-a-workflow-dispatch-event)
- POST `/repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches`
- Permissions:
- `repo`
- `actions:write`
- [List repository workflows](https://docs.github.com/en/rest/actions/workflows#list-repository-workflows)
- GET `/repos/{owner}/{repo}/actions/workflows`
- Permissions:
- `repo`
- `actions:read`
- [List workflow runs](https://docs.github.com/en/rest/actions/workflow-runs#list-workflow-runs-for-a-repository)
- GET `/repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs`
- Permissions:
- `repo`
- [List jobs for a workflow run](https://docs.github.com/en/rest/actions/workflow-jobs#list-jobs-for-a-workflow-run)
- GET `/repos/{owner}/{repo}/actions/runs/{run_id}/jobs`
- Permissions:
- `repo`
- `actions:read`
For more information please see [api.ts](./src/api.ts).
## Where does this help?
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).
## Flow
```ascii
┌─────────────────┐
│ │
│ Dispatch Action │
│ │
│ with unique ID │
│ │
└───────┬─────────┘
│
│
▼ ┌───────────────┐
┌────────────────┐ │ │
│ │ │ Request steps │
│ Request top 10 ├────────────────►│ │
│ │ │ for each run │
│ workflow runs │ │ │
│ │◄────────────────┤ and search │
└───────┬────────┘ Retry │ │
│ └───────┬───────┘
│ │
Timeout │ │
│ │
▼ ▼
┌──────┐ ┌───────────────┐
│ Fail │ │ Output run ID │
└──────┘ └───────────────┘
```