README.md

Repository Dispatch

A GitHub action to create a repository dispatch event.

Usage

Dispatch an event to the current repository by elivating the permissions of the default GITHUB_TOKEN.

permissions:
  actions: write

jobs:
  repositorydispatch:
    runs-on: ubuntu-latest
    steps:
      - name: Repository Dispatch
        uses: peter-evans/repository-dispatch@v2
        with:
          event-type: my-event

Dispatch an event to a remote repository using a repo scoped Personal Access Token (PAT).

      - name: Repository Dispatch
        uses: peter-evans/repository-dispatch@v2
        with:
          token: ${{ secrets.REPO_ACCESS_TOKEN }}
          event-type: my-event

Action inputs

Name	Description	Default
token	(required) GITHUB_TOKEN (permissions actions: write) or a repo scoped Personal Access Token (PAT). See token for further details.	GITHUB_TOKEN
repository	The full name of the repository to send the dispatch.	github.repository (current repository)
event-type	(required) A custom webhook event name.
client-payload	JSON payload with extra information about the webhook event that your action or workflow may use.	{}

Token

This action creates repository_dispatch events. The default GITHUB_TOKEN token can only be used if you are dispatching the same repository that the workflow is executing in. In this case you must elevate the token permissions to allow the dispatch.

permissions:
  actions: write

To dispatch to a remote repository you must create a Personal Access Token (PAT) with the repo scope and store it as a secret. If you will be dispatching to a public repository then you can use the more limited public_repo scope.

Example

Here is an example setting all of the input parameters.

      - name: Repository Dispatch
        uses: peter-evans/repository-dispatch@v2
        with:
          token: ${{ secrets.REPO_ACCESS_TOKEN }}
          repository: username/my-repo
          event-type: my-event
          client-payload: '{"ref": "${{ github.ref }}", "sha": "${{ github.sha }}"}'

Here is an example on: repository_dispatch workflow to receive the event. Note that repository dispatch events will only trigger a workflow run if the workflow is committed to the default branch.

name: Repository Dispatch
on:
  repository_dispatch:
    types: [my-event]
jobs:
  myEvent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          ref: ${{ github.event.client_payload.ref }}
      - run: echo ${{ github.event.client_payload.sha }}

Dispatch to multiple repositories

You can dispatch to multiple repositories by using a matrix strategy. In the following example, after the build job succeeds, an event is dispatched to three different repositories.

jobs:
  build:
    # Main workflow job that builds, tests, etc.

  dispatch:
    needs: build
    strategy:
      matrix:
        repo: ['my-org/repo1', 'my-org/repo2', 'my-org/repo3']
    runs-on: ubuntu-latest
    steps:
      - name: Repository Dispatch
        uses: peter-evans/repository-dispatch@v2
        with:
          token: ${{ secrets.REPO_ACCESS_TOKEN }}
          repository: ${{ matrix.repo }}
          event-type: my-event

Client payload

The GitHub API allows a maximum of 10 top-level properties in the client-payload JSON. If you use more than that you will see an error message like the following.

No more than 10 properties are allowed; 14 were supplied.

For example, this payload will fail because it has more than 10 top-level properties.

client-payload: ${{ toJson(github) }}

To solve this you can simply wrap the payload in a single top-level property. The following payload will succeed.

client-payload: '{"github": ${{ toJson(github) }}}'

Additionally, there is a limitation on the total data size of the client-payload. A very large payload may result in a client_payload is too large error.

License

MIT