Skip to content
A GitHub action that facilitates "ChatOps" by creating repository dispatch events for slash commands
JavaScript
Use this GitHub Action with your project

Add this Action to an existing workflow or create a new one.

View on Marketplace
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Update dispatch config Jan 5, 2020
assets Add image Jan 5, 2020
dist Package feature Jan 4, 2020
docs Update documentation Jan 5, 2020
src Add named args command config Jan 4, 2020
.eslintrc.json Add action Nov 24, 2019
.gitignore Add action Nov 24, 2019
LICENSE Initial commit Nov 24, 2019
README.md Update README Jan 5, 2020
action.yml Update documentation Jan 4, 2020
jest.config.js Add action Nov 24, 2019
package-lock.json Add action Nov 24, 2019
package.json Add action Nov 24, 2019

README.md

Slash Command Dispatch

GitHub Marketplace

A GitHub action that facilitates "ChatOps" by creating repository dispatch events for slash commands.

How does it work?

The action runs in issue_comment event workflows and checks comments for slash commands. 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.

Why repository dispatch?

"ChatOps" with slash commands can work in a basic way by parsing the commands during issue_comment events and immediately processing the command. In repositories with a lot of activity, the workflow queue will get backed up very quickly trying to handle new issue_comment events and process the commands themselves.

Dispatching commands to be processed elsewhere keeps the workflow queue moving quickly. It essentially enables parallel processing of workflows.

Demos

See it in action with the following live demos.

Documentation

Dispatching commands

Standard configuration

The following workflow should be configured in the repository where commands will be dispatched from. This example will respond to comments containing the slash commands /deploy, /integration-test and /build-docs.

name: Slash Command Dispatch
on:
  issue_comment:
    types: [created]
jobs:
  slashCommandDispatch:
    runs-on: ubuntu-latest
    steps:
      - name: Slash Command Dispatch
        uses: peter-evans/slash-command-dispatch@v1
        with:
          token: ${{ secrets.REPO_ACCESS_TOKEN }}
          commands: deploy, integration-test, build-docs

This action also features advanced configuration that allows each command to be configured individually if necessary. Use the standard configuration shown above unless you require advanced features.

Action inputs

Input Description Default
token (required) A repo scoped PAT.
reaction-token GITHUB_TOKEN or a repo scoped PAT.
reactions Add reactions. 👀 = seen, 🚀 = dispatched true
commands (required) A comma separated list of commands.
permission The repository permission level required by the user to dispatch commands. (none, read, write, admin) write
issue-type The issue type required for commands. (issue, pull-request, both) both
allow-edits Allow edited comments to trigger command dispatches. false
repository The full name of the repository to send the dispatch events. Current repository
event-type-suffix The repository dispatch event type suffix for the commands. -command
named-args Parse named arguments and add them to the command payload. false
config JSON configuration for commands. See Advanced configuration
config-from-file JSON configuration from a file for commands. See Advanced configuration

What is the reaction-token?

If you don't specify a token for reaction-token it will use the PAT supplied via token. 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.

      - name: Slash Command Dispatch
        uses: peter-evans/slash-command-dispatch@v1
        with:
          token: ${{ secrets.REPO_ACCESS_TOKEN }}
          reaction-token: ${{ secrets.GITHUB_TOKEN }}
          commands: deploy, integration-test, build-docs

Handling dispatched commands

Event types

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.

For example, if your slash command is integration-test, the event type will be integration-test-command.

on:
  repository_dispatch:
    types: [integration-test-command]

Accessing contexts

Commands are dispatched with a payload containing a number of contexts.

slash_command context

The slash command context can be accessed as follows. args is a space separated string of all the supplied arguments. Each argument is also supplied in a numbered property, i.e. arg1, arg2, arg3, etc.

      - name: Output command and arguments
        run: |
          echo ${{ github.event.client_payload.slash_command.command }}
          echo ${{ github.event.client_payload.slash_command.args }}
          echo ${{ github.event.client_payload.slash_command.arg1 }}
          echo ${{ github.event.client_payload.slash_command.arg2 }}
          echo ${{ github.event.client_payload.slash_command.arg3 }}
          # etc.

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.

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

    "slash_command": {
        "command": "deploy",
        "args": "branch=master env=prod some other args",
        "unnamed_args": "some other args",
        "branch": "master",
        "env": "prod",
        "arg1": "some",
        "arg2": "other",
        "arg3": "args"
    }

These named arguments can be accessed in a workflow as follows.

      - name: Output command and named arguments
        run: |
          echo ${{ github.event.client_payload.slash_command.command }}
          echo ${{ github.event.client_payload.slash_command.branch }}
          echo ${{ github.event.client_payload.slash_command.env }}
          echo ${{ github.event.client_payload.slash_command.unnamed_args }}

github and pull_request contexts

The payload contains the complete github context of the issue_comment event at path github.event.client_payload.github. Additionally, if the comment was made in a pull request, the action calls the GitHub API to fetch the pull request detail and attach it to the payload at path github.event.client_payload.pull_request.

You can inspect the payload with the following step.

      - name: Dump the client payload context
        env:
          PAYLOAD_CONTEXT: ${{ toJson(github.event.client_payload) }}
        run: echo "$PAYLOAD_CONTEXT"

Responding to the comment on command completion

Using create-or-update-comment action there are a number of ways you can respond to the comment once the command has completed.

The simplest response is to add a 🎉 reaction to the comment.

      - name: Add reaction
        uses: peter-evans/create-or-update-comment@v1
        with:
          token: ${{ secrets.REPO_ACCESS_TOKEN }}
          repository: ${{ github.event.client_payload.github.payload.repository.full_name }}
          comment-id: ${{ github.event.client_payload.github.payload.comment.id }}
          reaction-type: hooray

License

MIT

You can’t perform that action at this time.