mirror of
https://github.com/peter-evans/repository-dispatch.git
synced 2026-06-27 14:44:21 +00:00
77fb463884
Fix documentation related to tokens. The secrets.GITHUB_TOKEN provided by the GitHub Actions App can do everything related to the repo if we elevate its permissions, including calling workflow_dispatch and repository_dispatch. Some people in my organization are using PAT's instead of the secrets.GITHUB_TOKEN when using this action because of this README suggestion, even when they are calling the same repository. Using PATs in that contexts provides unnecessary security risks.
122 lines
4.7 KiB
Markdown
122 lines
4.7 KiB
Markdown
# Repository Dispatch
|
|
[](https://github.com/peter-evans/repository-dispatch/actions?query=workflow%3ACI)
|
|
[](https://github.com/marketplace/actions/repository-dispatch)
|
|
|
|
A GitHub action to create a repository dispatch event.
|
|
|
|
## Usage
|
|
|
|
```yml
|
|
- 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**) A GitHub access token with `actions: write` permission to the repository being dispatched. | |
|
|
| `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`](https://developer.github.com/v3/repos/#create-a-repository-dispatch-event) events. The default `GITHUB_TOKEN`
|
|
token can only be used if you are dispatching the same repo. In this case you must assign the permission `action: write` to the token, see [permissions api](https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs). Example:
|
|
```yaml
|
|
permissions:
|
|
actions: write
|
|
```
|
|
|
|
The solution to trigger other repositories is to manually create a PAT and store it as a secret e.g. `${{ secrets.PERSONAL_TOKEN }}`.
|
|
|
|
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.
|
|
|
|
```yml
|
|
- 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.
|
|
|
|
```yml
|
|
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](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix). In the following example, after the `build` job succeeds, an event is dispatched to three different repositories.
|
|
|
|
```yml
|
|
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.
|
|
|
|
```yml
|
|
client-payload: ${{ toJson(github) }}
|
|
```
|
|
|
|
To solve this you can simply wrap the payload in a single top-level property.
|
|
The following payload will succeed.
|
|
|
|
```yml
|
|
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](LICENSE)
|