Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rytswd/comvent
⚡️ Comvent - Simple control for GitHub Actions workflow with "comment event", allowing you to parse comments with regular expression
https://github.com/rytswd/comvent
github-actions typescript
Last synced: about 1 month ago
JSON representation
⚡️ Comvent - Simple control for GitHub Actions workflow with "comment event", allowing you to parse comments with regular expression
- Host: GitHub
- URL: https://github.com/rytswd/comvent
- Owner: rytswd
- License: mit
- Created: 2019-09-04T13:32:45.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2024-02-05T16:15:11.000Z (11 months ago)
- Last Synced: 2024-10-14T13:31:01.082Z (2 months ago)
- Topics: github-actions, typescript
- Language: TypeScript
- Homepage:
- Size: 21.5 MB
- Stars: 11
- Watchers: 3
- Forks: 1
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ⚡️ Comvent
> Simple control for GitHub Actions to handle "comment event" - a building block for rich comment handling
[](build-status) | [](mit) | [](releases)
[build-status]: https://github.com/rytswd/comvent/actions
[mit]: https://opensource.org/licenses/MIT
[releases]: https://github.com/rytswd/comvent/releases
## 🌅 Contents
- [Examples](#-examples)
- [Action Inputs](#-action-inputs)
- [Comvent Configuration File](#%EF%B8%8F-comvent-configuration-file)
- [Action Outputs](#-action-outputs)
## 🚀 Examples
Comvent is being used in this repo as well. You can check out [this issue](https://github.com/rytswd/comvent/issues/24) and comment to see the actual Comvent offerings in action! 🏃
### ChatBot Setup
It is pretty easy to provide simplistic ChatBot experience with PR / Issue comment.
You can add Comvent setup at the beginning of the `issue_comment` event, and use its output to run any step afterwards based on the patterns found. The below is an example to simply repsond to a comment.
> `.github/workflows/chatbot.yaml`
```yaml
- name: Handle with Comvent
uses: rytswd/[email protected]
id: comvent
with:
token: ${{ secrets.GITHUB_TOKEN }}
config-path: .github/comvent-chatbot.yaml
# The below only runs when Comvent finds matching comment.
# This assumes that Comvent config holding 'command-random' as a keyword.
- if: steps.comvent.outputs.command-random != ''
name: Handle random event
uses: actions/github-script@v3
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
# An example of responding to a comment.
script: |
const comment = `Command \`/random\` was triggered by the comment`;
github.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: comment
})
#
# You can repeat similar handling based on the Comvent config.
#
```
Click to view full example
> `.github/workflows/chatbot.yaml`
```yaml
name: ChatBot
on:
issue_comment:
# This shouldn't be called for comment deletion
types:
- created
- edited
jobs:
chatbot:
name: With latest code base
runs-on: ubuntu-latest
steps:
- name: Handle with Comvent
uses: rytswd/[email protected]
id: comvent
with:
token: ${{ secrets.GITHUB_TOKEN }}
config-path: .github/comvent-chatbot.yaml
# The below only runs when Comvent finds matching comment.
# This assumes that Comvent config holding 'command-random' as a keyword.
- if: steps.comvent.outputs.command-random != ''
name: Handle random event
uses: actions/github-script@v3
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
# An example of responding to a comment.
script: |
const comment = `Command \`/random\` was triggered by the comment`;
github.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: comment
})
#
# You can repeat similar handling based on the Comvent config.
#
```
As used above, Comvent configuration needs to define the keywords to find patterns.
> `.github/comvent-chatbot.yaml`
```yaml
---
version: 0.2.0
trigger: default
keywords:
- name: command-random
value: '^\/random$' # Regex which looks for a comment with '/random'
- name: some-other-command
value: 'some arbitrary regex setup'
# You can have as many regex setup as you need.
```
### Handle Abusive Content
You can add a simple automation to monitor abusive comments.
Using [github-script](https://github.com/actions/github-script), you can automatically remove such comment when Comvent finds one, while leaving a comment about the deletion.
> `.github/workflows/abuse-monitor.yaml`
```yaml
- name: Handle with Comvent
uses: rytswd/[email protected]
id: comvent
with:
token: ${{ secrets.GITHUB_TOKEN }}
config-path: .github/comvent-abuse-monitor.yaml
# The below only runs when Comvent finds matching comment.
# This assumes that Comvent config holding 'some-abusive-content' as a keyword.
- if: steps.comvent.outputs.some-abusive-content != ''
name: Handle some abusive content
uses: actions/github-script@v3
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
# An example of removing the abusive comment, and leaving a comment about the deletion.
script: |
github.issues.deleteComment({
owner: context.repo.owner,
repo: context.repo.repo,
comment_id: ${{ github.event.comment.id }}
})
const comment = `Found abusive comment! 😰
The comment was thus removed.`;
github.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: comment
})
```
Click to view full example
> `.github/workflows/abuse-monitor.yaml`
```yaml
name: Monitor Abusive Comments
on:
issue_comment:
# This shouldn't be called for comment deletion
types:
- created
- edited
jobs:
abuse-monitor:
name: With latest code base
runs-on: ubuntu-latest
steps:
- name: Handle with Comvent
uses: rytswd/[email protected]
id: comvent
with:
token: ${{ secrets.GITHUB_TOKEN }}
config-path: .github/comvent-abuse-monitor.yaml
# The below only runs when Comvent finds matching comment.
# This assumes that Comvent config holding 'some-abusive-content' as a keyword.
- if: steps.comvent.outputs.some-abusive-content != ''
name: Handle some abusive content
uses: actions/github-script@v3
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
# An example of removing the abusive comment, and leaving a comment about the deletion.
script: |
github.issues.deleteComment({
owner: context.repo.owner,
repo: context.repo.repo,
comment_id: ${{ github.event.comment.id }}
})
const comment = `Found abusive comment! 😰
The comment was thus removed.`;
github.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: comment
})
```
As used above, Comvent configuration needs to define the keywords to find patterns.
> `.github/comvent-abuse-monitor.yaml`
```yaml
---
version: 0.2.0
trigger: default
keywords:
- name: some-abusive-content
value: 'some abusive content' # Find abusive comment
```
## 🧪 Action Inputs
| Name | Description | IsRequired |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------: |
| `token` | `GITHUB_TOKEN` or Personal Access Token with `repo` scope | Yes |
| `config-path` | Path to Comvent configuration file. You can find more about the configuration below. Defaults to `.github/comvent-setup.yaml`. Regardless of your GitHub Action setup, this assumes the current directory is the root of your repository. | |
| `config-check-only` | A flag to run only Comvent configuration setup. Used for testing only. | |
## ⚙️ Comvent Configuration File
Comvent uses a dedicated YAML file for its configuration.
### Example
The below is the copy of [`.github/comvent-setup.yaml`](https://github.com/rytswd/comvent/blob/main/.github/comvent-setup.yaml).
```yaml
---
# version determines the supported values and how they are handled. The current
# latest is 0.2.0, and if not speccified, it infers the latest version.
version: 0.2.0
# trigger can accept either `default` or `specific`.
# - default: all comments will be handled by Comvent, except for those from
# users listed under users.inactive list below.
# - specific: only comments made by specified users under users.active list
# below gets handled by Comvent.
trigger: default
# users is consisted of `active` or `inactive` user list. Providing a list
# which does not match the `trigger` setup above is simply ignored.
users:
active:
- rytswd # This is no-op, as the `trigger` above is set to `default`
inactive:
- random-user
- another-user
# keywords is a list comprised of `name` and `value` fields.
# - name: used for Comvent output, and thus should not include whitespace.
# - value: regex value to search for. The search takes place for each line in
# the comment.
keywords:
- name: command-random
value: '^\/random$' # Regex which looks for a comment with '/random'
```
You can find a few examples in [`.github/`](https://github.com/rytswd/comvent/tree/main/.github) directory.
### Configuration Details
| Key | Description | Default |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `version` | The version of configuration spec. The latest is `0.2.0`. This may not be in line with the released version as of now, until Comvent releases v1.0 | `0.2.0` |
| `trigger` | When to handle Comvent. `default` means event triggered by anyone would be handled by Comvent, and `specific` means only specified users' comments would be handled. | `default` |
| `users` | Stanza with `active` or `inactive` with list of GitHub user accounts. `active` list is only used for `specific` trigger setup, and `inactive` is for `default` trigger setup. | |
| `keywords` | Keywords to process comment based on. Each `value` is regex searched in comment, for each line. | |
## 🍸 Action Outputs
Comvent provides the outputs with which you can tweak your Action worrkflow.
As the outputs will be based on the [Comvent Configuration File](#%EF%B8%8F-comvent-configuration-file) provided to Comvent, the below table is based on the following simple configuration as an example.
> `.github/comvent-config.yaml`
```yaml
---
version: 0.2.0
trigger: default
keywords:
- name: command-random
value: '^\/random$'
- name: some-other-command
value: 'some arbitrary regex setup'
- name: command-echo
value: '^\/echo (.+)$'
```
| Name | Description |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `comvent-found-any-match` | Special keyword provided by Comvent by default. If any keyword is matched, this will provide `found` as output. |
| (Example)
`command-random` | When the RegExp condition is matched, the entire line will be returned as the output. With the above example, this will be `/random`. |
| (Example)
`some-other-command` | When the RegExp condition is matched, the entire line will be returned as the output. With the above example, this will be something like `Test test - some arbitrary regex setup - test test`. |
| (Example)
`command-echo` | When the RegExp condition with group is matched, the first group match will be returned, and if the first group is an empty string, it would instead return the entire line. For example, with the above example, if the comment was `/echo this is a test message.`, the output will be `this is a test message.`. |