From 9604e4dbf850076f73c85055851fb811ba44c65f Mon Sep 17 00:00:00 2001 From: Peter Evans Date: Fri, 24 Jul 2020 10:38:59 +0900 Subject: [PATCH] Add explanation of dispatch type differences --- README.md | 10 +++++++++- docs/workflow-dispatch.md | 2 +- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 63c9ed9..865c6f3 100644 --- a/README.md +++ b/README.md @@ -111,9 +111,17 @@ You can use a [PAT](https://help.github.com/en/github/authenticating-to-github/c By default, the action creates [repository_dispatch](https://developer.github.com/v3/repos/#create-a-repository-dispatch-event) events. Setting `dispatch-type` to `workflow` will instead create [workflow_dispatch](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch) events. - There are significant differences in the action's behaviour when using `workflow` dispatch. See [workflow dispatch](docs/workflow-dispatch.md) for usage details. +For the majority of use cases, the default `repository` dispatch will likely be the most suitable for new workflows. +If you already have `workflow_dispatch` workflows, you can execute them with slash commands using this action. + +| Repository Dispatch (default) | Workflow Dispatch | +| --- | --- | +| Events are created with a `client_payload` giving the target workflow access to a wealth of useful [context properties](https://github.com/peter-evans/slash-command-dispatch/tree/dev#accessing-contexts). | A `client_payload` cannot be sent with [workflow_dispatch](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch) events. The target workflow can only make use of up to 10 pre-defined inputs, the names of which must match named arguments supplied with the slash command. | +| Slash commands can only execute workflows in the target repository's default branch. | Slash commands can execute workflows in any branch using the `ref` named argument. The reference can be a branch, tag, or a commit SHA. | +| Immediate command validation feedback is unavailable when creating the dispatch event. | Immediate command [validation feedback](https://github.com/peter-evans/slash-command-dispatch/blob/dev/docs/workflow-dispatch.md#validation-errors) is available as an action output. | + ### How comments are parsed for slash commands Slash commands must be placed in the first line of the comment to be interpreted as a command. diff --git a/docs/workflow-dispatch.md b/docs/workflow-dispatch.md index d2b3133..32376d7 100644 --- a/docs/workflow-dispatch.md +++ b/docs/workflow-dispatch.md @@ -11,7 +11,7 @@ There are significant differences in the action's behaviour when using `workflow - When issuing a slash command with arguments, *only named arguments are accepted*. Unnamed arguments will be ignored. - A maximum of 10 named arguments are accepted. Additional named arguments after the first 10 will be ignored. - `ref` is a reserved named argument that does not count towards the maximum of 10. This is used to specify the target reference of the command. The reference can be a branch, tag, or a commit SHA. If you omit the `ref` argument, the target repository's default branch will be used. -- A `client_payload` context cannot be sent with [workflow_dispatch](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch) events. The target workflow can only make use of up to 10 pre-defined inputs, the names of which must match the named arguments supplied with the slash command. +- A `client_payload` context cannot be sent with [workflow_dispatch](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch) events. The target workflow can only make use of up to 10 pre-defined inputs, the names of which must match named arguments supplied with the slash command. ## Handling dispatched commands