{"id":26552764,"url":"https://github.com/codex-/return-dispatch","last_synced_at":"2025-03-22T08:49:30.337Z","repository":{"id":38184077,"uuid":"387295484","full_name":"Codex-/return-dispatch","owner":"Codex-","description":"⚙️ Dispatch an action to a foreign repository and output the newly created run ID. ","archived":false,"fork":false,"pushed_at":"2024-05-03T22:02:13.000Z","size":3810,"stargazers_count":32,"open_issues_count":4,"forks_count":10,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-05-03T23:22:01.536Z","etag":null,"topics":["actions","dispatch","github-actions","workflow"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Codex-.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-19T00:23:53.000Z","updated_at":"2024-05-30T14:47:27.937Z","dependencies_parsed_at":"2023-01-05T04:49:02.117Z","dependency_job_id":"e29eb5b8-9961-483c-a9ff-ea60b803ad8e","html_url":"https://github.com/Codex-/return-dispatch","commit_stats":{"total_commits":204,"total_committers":3,"mean_commits":68.0,"dds":0.3382352941176471,"last_synced_commit":"65dd6874683d1f2564bb0eadc051000041ce5e0d"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":"actions/typescript-action","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Codex-%2Freturn-dispatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Codex-%2Freturn-dispatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Codex-%2Freturn-dispatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Codex-%2Freturn-dispatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Codex-","download_url":"https://codeload.github.com/Codex-/return-dispatch/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244931591,"owners_count":20534011,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actions","dispatch","github-actions","workflow"],"created_at":"2025-03-22T08:49:29.903Z","updated_at":"2025-03-22T08:49:30.325Z","avatar_url":"https://github.com/Codex-.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitHub Action: return-dispatch\n\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/codex-/return-dispatch/test.yml?style=flat-square)](https://github.com/Codex-/return-dispatch/actions/workflows/test.yml) [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier) [![codecov](https://img.shields.io/codecov/c/github/Codex-/return-dispatch?style=flat-square)](https://codecov.io/gh/Codex-/return-dispatch) [![GitHub Marketplace](https://img.shields.io/badge/Marketplace-return–dispatch-blue.svg?colorA=24292e\u0026colorB=0366d6\u0026style=flat-square\u0026longCache=true\u0026logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAM6wAADOsB5dZE0gAAABl0RVh0U29mdHdhcmUAd3d3Lmlua3NjYXBlLm9yZ5vuPBoAAAERSURBVCiRhZG/SsMxFEZPfsVJ61jbxaF0cRQRcRJ9hlYn30IHN/+9iquDCOIsblIrOjqKgy5aKoJQj4O3EEtbPwhJbr6Te28CmdSKeqzeqr0YbfVIrTBKakvtOl5dtTkK+v4HfA9PEyBFCY9AGVgCBLaBp1jPAyfAJ/AAdIEG0dNAiyP7+K1qIfMdonZic6+WJoBJvQlvuwDqcXadUuqPA1NKAlexbRTAIMvMOCjTbMwl1LtI/6KWJ5Q6rT6Ht1MA58AX8Apcqqt5r2qhrgAXQC3CZ6i1+KMd9TRu3MvA3aH/fFPnBodb6oe6HM8+lYHrGdRXW8M9bMZtPXUji69lmf5Cmamq7quNLFZXD9Rq7v0Bpc1o/tp0fisAAAAASUVORK5CYII=)](https://github.com/marketplace/actions/return-dispatch)\n\nDispatch an action to a foreign repository and output the newly created run ID.\n\nThis Action exists as a workaround for the issue where dispatching an action to foreign repository does not return any kind of identifier.\n\n## Usage\n\nEnsure you have configured your remote action correctly, see below for an example.\n\n### Dispatching Repository Action\n\n```yaml\nsteps:\n  - name: Dispatch an action and get the run ID and URL\n    uses: codex-/return-dispatch@v2\n    id: return_dispatch\n    with:\n      token: ${{ secrets.TOKEN }} # Note this is NOT GITHUB_TOKEN but a PAT\n      ref: target_branch # or refs/heads/target_branch\n      repo: repository-name\n      owner: repository-owner\n      workflow: automation-test.yml\n      workflow_inputs: '{ \"some_input\": \"value\" }' # Optional\n      workflow_timeout_seconds: 120 # Default: 300\n      workflow_job_steps_retry_seconds:\n        # Lineal backoff retry attempts are made where the attempt count is\n        # the magnitude and the scaling value is `workflow_job_steps_retry_seconds`\n        10 # Default: 5\n      distinct_id: someDistinctId # Optional\n\n  - name: Use the output run ID and URL\n    run: |\n      echo ${{steps.return_dispatch.outputs.run_id}}\n      echo ${{steps.return_dispatch.outputs.run_url}}\n```\n\n### Receiving Repository Action\n\nIn the earliest possible stage for the Action, add the input into the name.\n\nAs every step needs a `uses` or `run`, simply `echo` the ID or similar to satisfy this requirement.\n\n```yaml\nname: action-test\non:\n  workflow_dispatch:\n    inputs:\n      distinct_id:\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - name: echo distinct ID ${{ github.event.inputs.distinct_id }}\n        run: echo ${{ github.event.inputs.distinct_id }}\n```\n\n## Token\n\nTo 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.\n\n### Permissions Required\n\nThe permissions required for this action to function correctly are:\n\n- `repo` scope\n  - You may get away with simply having `repo:public_repo`\n  - `repo` is definitely needed if the repository is private.\n- `actions:read`\n- `actions:write`\n\n### APIs Used\n\nFor the sake of transparency please note that this action uses the following API calls:\n\n- [Create a workflow dispatch event](https://docs.github.com/en/rest/actions/workflows#create-a-workflow-dispatch-event)\n  - POST `/repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches`\n  - Permissions:\n    - `repo`\n    - `actions:write`\n- [List repository workflows](https://docs.github.com/en/rest/actions/workflows#list-repository-workflows)\n  - GET `/repos/{owner}/{repo}/actions/workflows`\n  - Permissions:\n    - `repo`\n    - `actions:read`\n- [List workflow runs](https://docs.github.com/en/rest/actions/workflow-runs#list-workflow-runs-for-a-repository)\n  - GET `/repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs`\n  - Permissions:\n    - `repo`\n- [List jobs for a workflow run](https://docs.github.com/en/rest/actions/workflow-jobs#list-jobs-for-a-workflow-run)\n  - GET `/repos/{owner}/{repo}/actions/runs/{run_id}/jobs`\n  - Permissions:\n    - `repo`\n    - `actions:read`\n\nFor more information please see [api.ts](./src/api.ts).\n\n## Where does this help?\n\nIf 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.\n\nThe 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).\n\n## Flow\n\n```ascii\n┌─────────────────┐\n│                 │\n│ Dispatch Action │\n│                 │\n│ with unique ID  │\n│                 │\n└───────┬─────────┘\n        │\n        │\n        ▼                          ┌───────────────┐\n┌────────────────┐                 │               │\n│                │                 │ Request steps │\n│ Request top 10 ├────────────────►│               │\n│                │                 │ for each run  │\n│ workflow runs  │                 │               │\n│                │◄────────────────┤ and search    │\n└───────┬────────┘     Retry       │               │\n        │                          └───────┬───────┘\n        │                                  │\nTimeout │                                  │\n        │                                  │\n        ▼                                  ▼\n     ┌──────┐                      ┌───────────────┐\n     │ Fail │                      │ Output run ID │\n     └──────┘                      └───────────────┘\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodex-%2Freturn-dispatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodex-%2Freturn-dispatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodex-%2Freturn-dispatch/lists"}