GitHub Action: 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

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}}

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.

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
  • POST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches
  • Permissions:
    • repo
    • actions:write
• List repository workflows
  • GET /repos/{owner}/{repo}/actions/workflows
  • Permissions:
    • repo
    • actions:read
• List workflow runs
  • GET /repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs
  • Permissions:
    • repo
• 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.

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

┌─────────────────┐
│                 │
│ Dispatch Action │
│                 │
│ with unique ID  │
│                 │
└───────┬─────────┘
        │
        │
        ▼                          ┌───────────────┐
┌────────────────┐                 │               │
│                │                 │ Request steps │
│ Request top 10 ├────────────────►│               │
│                │                 │ for each run  │
│ workflow runs  │                 │               │
│                │◄────────────────┤ and search    │
└───────┬────────┘     Retry       │               │
        │                          └───────┬───────┘
        │                                  │
Timeout │                                  │
        │                                  │
        ▼                                  ▼
     ┌──────┐                      ┌───────────────┐
     │ Fail │                      │ Output run ID │
     └──────┘                      └───────────────┘