Skip to content

Commit 0c9ea47

Browse files
peter-evanspeter-evans
committed
Update README
1 parent b111e23 commit 0c9ea47

File tree

1 file changed

+159
-2
lines changed

1 file changed

+159
-2
lines changed

‎README.md

Lines changed: 159 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,160 @@
1-
# slash-command-dispatch
1+
# Slash Command Dispatch
2+
[![GitHub Marketplace](https://img.shields.io/badge/Marketplace-Slash%20Command%20Dispatch-blue.svg?colorA=24292e&colorB=0366d6&style=flat&longCache=true&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAM6wAADOsB5dZE0gAAABl0RVh0U29mdHdhcmUAd3d3Lmlua3NjYXBlLm9yZ5vuPBoAAAERSURBVCiRhZG/SsMxFEZPfsVJ61jbxaF0cRQRcRJ9hlYn30IHN/+9iquDCOIsblIrOjqKgy5aKoJQj4O3EEtbPwhJbr6Te28CmdSKeqzeqr0YbfVIrTBKakvtOl5dtTkK+v4HfA9PEyBFCY9AGVgCBLaBp1jPAyfAJ/AAdIEG0dNAiyP7+K1qIfMdonZic6+WJoBJvQlvuwDqcXadUuqPA1NKAlexbRTAIMvMOCjTbMwl1LtI/6KWJ5Q6rT6Ht1MA58AX8Apcqqt5r2qhrgAXQC3CZ6i1+KMd9TRu3MvA3aH/fFPnBodb6oe6HM8+lYHrGdRXW8M9bMZtPXUji69lmf5Cmamq7quNLFZXD9Rq7v0Bpc1o/tp0fisAAAAASUVORK5CYII=)](https://github.com/marketplace/actions/slash-command-dispatch)
23

3-
A GitHub action that facilitates "ChatOps" by creating repository dispatch events for slash commands
4+
A GitHub action that facilitates "ChatOps" by creating repository dispatch events for slash commands.
5+
6+
### How does it work?
7+
8+
The action runs in `on: issue_comment` workflows and checks comments for slash commands.
9+
When a valid command is found it creates a repository dispatch event that includes a payload containing full details of the command and its context.
10+
11+
### Why repository dispatch?
12+
13+
"ChatOps" with slash commands can work in a basic way by parsing the commands during `issue_comment` events and immediately processing the command.
14+
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.
15+
16+
Dispatching commands to be processed elsewhere keeps the workflow queue moving quickly. It essentially allows you to run multiple workflow queues in parallel.
17+
18+
### Advantages of slash-command-dispatch
19+
20+
- Easy configuration of "ChatOps" slash commands
21+
- Separating the queue of `issue_comment` events from the queue of commands to process keeps it fast moving
22+
- Users receive faster feedback that commands have been seen and are waiting to be processed
23+
- The ability to handle processing workloads 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 processed in the same repository, separation of comment parsing and command processing logic allows easier management of "ChatOps" use cases
26+
27+
### Demo
28+
29+
30+
31+
## Usage
32+
33+
### Basic configuration
34+
35+
```yml
36+
name: Slash Command Dispatch
37+
on:
38+
issue_comment:
39+
types: [created]
40+
jobs:
41+
slashCommandDispatch:
42+
runs-on: ubuntu-latest
43+
steps:
44+
- name: Slash Command Dispatch
45+
uses: peter-evans/slash-command-dispatch@v1
46+
with:
47+
token: ${{ secrets.REPO_ACCESS_TOKEN }}
48+
commands: rebase, integration-test, create-ticket
49+
repository: peter-evans/slash-command-dispatch-processor
50+
```
51+
52+
### Action inputs
53+
54+
| Name | Description | Default |
55+
| --- | --- | --- |
56+
| `token` | (**required**) A `repo` scoped [PAT](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line). | |
57+
| `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). | |
58+
| `reactions` | Add reactions to comments containing commands. | `true` |
59+
| `commands` | (**required**) A comma separated list of commands to dispatch. | |
60+
| `permission` | The permission level required by the user to dispatch commands. (`none`, `read`, `write`, `admin`) | `write` |
61+
| `issue-type` | The issue type required for commands. (`issue`, `pull-request`, `both`) | `both` |
62+
| `allow-edits` | Allow edited comments to trigger command dispatches. | `false` |
63+
| `repository` | The full name of the repository to send the dispatch events. | Current repository |
64+
| `event-type-suffix` | The repository dispatch event type suffix for the commands. | `-command` |
65+
| `config` | JSON configuration for commands. | |
66+
| `config-from-file` | JSON configuration from a file for commands. | |
67+
68+
### Handling dispatched commands
69+
70+
Repository dispatch events have a `type` to distinguish between events. The `type` set by the action is a combination of the slash command and `event-type-suffix`. The `event-type-suffix` input defaults to `-command`.
71+
72+
For example, if your slash command is `integration-test`, the event type will be `integration-test-command`.
73+
74+
```yml
75+
on:
76+
repository_dispatch:
77+
types: [integration-test-command]
78+
```
79+
80+
### What is the reaction-token?
81+
82+
If you don't specify a token for `reaction-token` it will use the [PAT](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) supplied via `token`.
83+
This means that reactions to comments will appear to be made by the user account associated with the PAT. If you prefer to have the @github-actions bot user react to comments you can set `reaction-token` to `GITHUB_TOKEN`.
84+
85+
```yml
86+
- name: Slash Command Dispatch
87+
uses: peter-evans/slash-command-dispatch@v1
88+
with:
89+
token: ${{ secrets.REPO_ACCESS_TOKEN }}
90+
reaction-token: ${{ secrets.GITHUB_TOKEN }}
91+
commands: rebase, integration-test, create-ticket
92+
```
93+
94+
### Advanced configuration
95+
96+
Using JSON configuration allows the options for each command to be customised.
97+
98+
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.
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+
},
128+
{
129+
"command": "create-ticket",
130+
"permission": "write",
131+
"issue_type": "issue",
132+
"allow_edits": true,
133+
"event_type_suffix": "-cmd"
134+
}
135+
]
136+
```
137+
138+
An example using the `config-from-file` input to set JSON configuration.
139+
Note that `actions/checkout` is required to access the file.
140+
141+
```yml
142+
name: Slash Command Dispatch
143+
on:
144+
issue_comment:
145+
types: [created]
146+
jobs:
147+
slashCommandDispatch:
148+
runs-on: ubuntu-latest
149+
steps:
150+
- uses: actions/checkout@v1
151+
- name: Slash Command Dispatch
152+
uses: peter-evans/slash-command-dispatch@v1
153+
with:
154+
token: ${{ secrets.REPO_ACCESS_TOKEN }}
155+
config-from-file: .github/slash-command-dispatch.json
156+
```
157+
158+
## License
159+
160+
[MIT](LICENSE)

0 commit comments

Comments
 (0)