Skip to content

Commit d77323e

Browse files
committed
Update documentation
1 parent 441a282 commit d77323e

File tree

3 files changed

+128
-90
lines changed

3 files changed

+128
-90
lines changed

README.md

Lines changed: 24 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -13,16 +13,16 @@ When a valid command is found it creates a repository dispatch event that includ
1313
"ChatOps" with slash commands can work in a basic way by parsing the commands during `issue_comment` events and immediately processing the command.
1414
In repositories with a lot of activity, the workflow queue will get backed up very quickly if it is trying to handle new comments for commands *and* process the commands themselves.
1515

16-
Dispatching commands to be processed elsewhere keeps the workflow queue moving quickly. It essentially allows you to run multiple workflow queues in parallel.
16+
Dispatching commands to be processed elsewhere keeps the workflow queue moving quickly. It essentially enables parallel processing of workflows.
1717

1818
### Key features
1919

20-
- Easy configuration of "ChatOps" slash commands
2120
- Enables separating the queue of `issue_comment` events from the queue of dispatched commands to keep it fast moving
2221
- Users receive faster feedback that commands have been seen and are waiting to be processed
2322
- The ability to handle processing commands in multiple repositories in parallel
24-
- Long running workloads can be processed in a repository workflow queue of their own
25-
- Even if commands are dispatched and processed in the same repository, separation of comment parsing and command processing makes workflows more maintainable, and with less duplication
23+
- Long running workloads can be separated to a repository workflow queue of their own
24+
25+
Even if commands are dispatched and processed in the same repository, separation of comment parsing and command processing makes workflows more maintainable, and with less duplication.
2626

2727
### Demo and examples
2828

@@ -37,7 +37,9 @@ See [examples](examples.md) for command patterns and example workflows.
3737

3838
## Dispatching commands
3939

40-
### Basic configuration
40+
### Dispatch configuration
41+
42+
This workflow should be configured in the repository where commands will be dispatched from.
4143

4244
```yml
4345
name: Slash Command Dispatch
@@ -57,23 +59,22 @@ jobs:
5759
5860
### Action inputs
5961
60-
For basic configuration, use the inputs in the leftmost column.
61-
Use the JSON properties for [Advanced configuration](#advanced-configuration).
62-
63-
| Input | JSON Property | Description | Default |
64-
| --- | --- | --- | --- |
65-
| `token` | | (**required**) A `repo` scoped [PAT](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line). | |
66-
| `reaction-token` | | `GITHUB_TOKEN` or a `repo` scoped [PAT](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line). | |
67-
| `reactions` | | Add reactions. :eyes: = seen, :rocket: = dispatched | `true` |
68-
| `commands` | `command` | (**required**) Input: A comma separated list of commands to dispatch. JSON property: A single command. | |
69-
| `permission` | `permission` | The repository permission level required by the user to dispatch commands. (`none`, `read`, `write`, `admin`) | `write` |
70-
| `issue-type` | `issue_type` | The issue type required for commands. (`issue`, `pull-request`, `both`) | `both` |
71-
| `allow-edits` | `allow_edits` | Allow edited comments to trigger command dispatches. | `false` |
72-
| `repository` | `repository` | The full name of the repository to send the dispatch events. | Current repository |
73-
| `event-type-suffix` | `event_type_suffix` | The repository dispatch event type suffix for the commands. | `-command` |
74-
| `named-args` | `named_args` | Parse named arguments and add them to the command payload. | `false` |
75-
| `config` | | JSON configuration for commands. See [Advanced configuration](#advanced-configuration) | |
76-
| `config-from-file` | | JSON configuration from a file for commands. See [Advanced configuration](#advanced-configuration) | |
62+
| Input | Description | Default |
63+
| --- | --- | --- |
64+
| `token` | (**required**) A `repo` scoped [PAT](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line). | |
65+
| `reaction-token` | `GITHUB_TOKEN` or a `repo` scoped [PAT](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line). | |
66+
| `reactions` | Add reactions. :eyes: = seen, :rocket: = dispatched | `true` |
67+
| `commands` | (**required**) Input: A comma separated list of commands to dispatch. JSON property: A single command. | |
68+
| `permission` | The repository permission level required by the user to dispatch commands. (`none`, `read`, `write`, `admin`) | `write` |
69+
| `issue-type` | The issue type required for commands. (`issue`, `pull-request`, `both`) | `both` |
70+
| `allow-edits` | Allow edited comments to trigger command dispatches. | `false` |
71+
| `repository` | The full name of the repository to send the dispatch events. | Current repository |
72+
| `event-type-suffix` | The repository dispatch event type suffix for the commands. | `-command` |
73+
| `named-args` | Parse named arguments and add them to the command payload. | `false` |
74+
| `config` | | JSON configuration for commands. See [Advanced configuration](docs/advanced-configuration.md) | |
75+
| `config-from-file` | | JSON configuration from a file for commands. See [Advanced configuration](docs/advanced-configuration.md) | |
76+
77+
This action also features [advanced configuration](docs/advanced-configuration.md) that allows each command to be configured individually if necessary.
7778

7879
### What is the reaction-token?
7980

@@ -89,73 +90,6 @@ This means that reactions to comments will appear to be made by the user account
8990
commands: rebase, integration-test, create-ticket
9091
```
9192

92-
### Advanced configuration
93-
94-
Using JSON configuration allows the options for each command to be specified individually.
95-
96-
Note that it's recommended to write the JSON configuration directly in the workflow rather than use a file. Using the `config-from-file` input will be slightly slower due to requiring the repository to be checked out with `actions/checkout` so the file can be accessed.
97-
98-
Here is an example workflow. Take care to use the correct JSON property names.
99-
100-
```yml
101-
name: Slash Command Dispatch
102-
on:
103-
issue_comment:
104-
types: [created]
105-
jobs:
106-
slashCommandDispatch:
107-
runs-on: ubuntu-latest
108-
steps:
109-
- name: Slash Command Dispatch
110-
uses: peter-evans/slash-command-dispatch@v1
111-
with:
112-
token: ${{ secrets.REPO_ACCESS_TOKEN }}
113-
reaction-token: ${{ secrets.GITHUB_TOKEN }}
114-
config: >
115-
[
116-
{
117-
"command": "rebase",
118-
"permission": "admin",
119-
"issue_type": "pull-request",
120-
"repository": "peter-evans/slash-command-dispatch-processor"
121-
},
122-
{
123-
"command": "integration-test",
124-
"permission": "write",
125-
"issue_type": "both",
126-
"repository": "peter-evans/slash-command-dispatch-processor",
127-
"named_args": true
128-
},
129-
{
130-
"command": "create-ticket",
131-
"permission": "write",
132-
"issue_type": "issue",
133-
"allow_edits": true,
134-
"event_type_suffix": "-cmd"
135-
}
136-
]
137-
```
138-
139-
The following workflow is an example using the `config-from-file` input to set JSON configuration.
140-
Note that `actions/checkout` is required to access the file.
141-
142-
```yml
143-
name: Slash Command Dispatch
144-
on:
145-
issue_comment:
146-
types: [created]
147-
jobs:
148-
slashCommandDispatch:
149-
runs-on: ubuntu-latest
150-
steps:
151-
- uses: actions/checkout@v2
152-
- name: Slash Command Dispatch
153-
uses: peter-evans/slash-command-dispatch@v1
154-
with:
155-
token: ${{ secrets.REPO_ACCESS_TOKEN }}
156-
config-from-file: .github/slash-command-dispatch.json
157-
```
158-
15993
## Handling dispatched commands
16094

16195
### Event types
@@ -191,7 +125,7 @@ Each argument is also supplied in a numbered property, i.e. `arg1`, `arg2`, `arg
191125
# etc.
192126
```
193127

194-
If the `named-args` input (or `named_args` JSON property) is set to `true`, any arguments that are prefixed in the format `name=argument` will be parsed and added to the payload.
128+
If the `named-args` input is set to `true`, any arguments that are prefixed in the format `name=argument` will be parsed and added to the payload.
195129

196130
For example, the slash command `/deploy branch=master env=prod some other args` will be set in the JSON payload as follows.
197131

docs/advanced-configuration.md

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Advanced configuration
2+
3+
## What is advanced configuration?
4+
5+
Due to the limitations of yaml based action inputs, basic configuration is not adequate enough to support unique configuration *per command*.
6+
7+
For example, the following basic configuration means that all commands must have the same `admin` permission.
8+
9+
```yml
10+
- name: Slash Command Dispatch
11+
uses: peter-evans/slash-command-dispatch@v1
12+
with:
13+
token: ${{ secrets.REPO_ACCESS_TOKEN }}
14+
commands: rebase, integration-test, create-ticket
15+
permission: admin
16+
```
17+
18+
To solve this issue, advanced JSON configuration allows each command to be configured individually.
19+
20+
## Advanced action inputs
21+
22+
Advanced configuration requires a combination of yaml based inputs and JSON configuration.
23+
24+
| Input | JSON Property | Description | Default |
25+
| --- | --- | --- | --- |
26+
| `token` | | (**required**) A `repo` scoped [PAT](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line). | |
27+
| `reaction-token` | | `GITHUB_TOKEN` or a `repo` scoped [PAT](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line). | |
28+
| `reactions` | | Add reactions. :eyes: = seen, :rocket: = dispatched | `true` |
29+
| | `command` | (**required**) Input: A comma separated list of commands to dispatch. JSON property: A single command. | |
30+
| | `permission` | The repository permission level required by the user to dispatch commands. (`none`, `read`, `write`, `admin`) | `write` |
31+
| | `issue_type` | The issue type required for commands. (`issue`, `pull-request`, `both`) | `both` |
32+
| | `allow_edits` | Allow edited comments to trigger command dispatches. | `false` |
33+
| | `repository` | The full name of the repository to send the dispatch events. | Current repository |
34+
| | `event_type_suffix` | The repository dispatch event type suffix for the commands. | `-command` |
35+
| | `named_args` | Parse named arguments and add them to the command payload. | `false` |
36+
| `config` | | JSON configuration for commands. See [Advanced configuration](#advanced-configuration) | |
37+
| `config-from-file` | | JSON configuration from a file for commands. See [Advanced configuration](#advanced-configuration) | |
38+
39+
## Dispatching commands
40+
41+
There are two ways to specify JSON configuration for command dispatch. Directly in the workflow via the `config` input, OR, specifing a JSON config file via the `config-from-file` input.
42+
43+
**Note**: It is recommended to write the JSON configuration directly in the workflow rather than use a file. Using the `config-from-file` input will be slightly slower due to requiring the repository to be checked out with `actions/checkout` so the file can be accessed.
44+
45+
Here is a reference example workflow. Take care to use the correct [JSON property names](#advanced-action-inputs).
46+
47+
```yml
48+
name: Slash Command Dispatch
49+
on:
50+
issue_comment:
51+
types: [created]
52+
jobs:
53+
slashCommandDispatch:
54+
runs-on: ubuntu-latest
55+
steps:
56+
- name: Slash Command Dispatch
57+
uses: peter-evans/slash-command-dispatch@v1
58+
with:
59+
token: ${{ secrets.REPO_ACCESS_TOKEN }}
60+
reaction-token: ${{ secrets.GITHUB_TOKEN }}
61+
config: >
62+
[
63+
{
64+
"command": "rebase",
65+
"permission": "admin",
66+
"issue_type": "pull-request",
67+
"repository": "peter-evans/slash-command-dispatch-processor"
68+
},
69+
{
70+
"command": "integration-test",
71+
"permission": "write",
72+
"issue_type": "both",
73+
"repository": "peter-evans/slash-command-dispatch-processor",
74+
"named_args": true
75+
},
76+
{
77+
"command": "create-ticket",
78+
"permission": "write",
79+
"issue_type": "issue",
80+
"allow_edits": true,
81+
"event_type_suffix": "-cmd"
82+
}
83+
]
84+
```
85+
86+
The following workflow is an example using the `config-from-file` input to set JSON configuration.
87+
Note that `actions/checkout` is required to access the file.
88+
89+
```yml
90+
name: Slash Command Dispatch
91+
on:
92+
issue_comment:
93+
types: [created]
94+
jobs:
95+
slashCommandDispatch:
96+
runs-on: ubuntu-latest
97+
steps:
98+
- uses: actions/checkout@v2
99+
- name: Slash Command Dispatch
100+
uses: peter-evans/slash-command-dispatch@v1
101+
with:
102+
token: ${{ secrets.REPO_ACCESS_TOKEN }}
103+
config-from-file: .github/slash-command-dispatch.json
104+
```
File renamed without changes.

0 commit comments

Comments
 (0)