Skip to content
You're viewing an older version of this GitHub Action. Do you want to see the latest version instead?
target

GitHub Action

Repository Dispatch

v1.1.3

Repository Dispatch

target

Repository Dispatch

Create a repository dispatch event

Installation

Copy and paste the following snippet into your .yml file.

 
              
- name: Repository Dispatch

              
  uses: peter-evans/repository-dispatch@v1.1.3
Learn more about this action in peter-evans/repository-dispatch

Choose a version

Repository Dispatch

CI GitHub Marketplace

A GitHub action to create a repository dispatch event.

Usage

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

Action inputs

Name Description Default
token (required) A repo scoped GitHub Personal Access Token. See token for further details.
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 does not have scopes to do this so a repo scoped PAT created on a user with write access to the target repository is required. 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@v1
        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 (usually master).

name: Repository Dispatch
on:
  repository_dispatch:
    types: [my-event]
jobs:
  myEvent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        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@v1
        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