Repository files navigation

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

The action runs inissue_comment event workflows and checks the first line of comments for slash commands.When a valid command is found it creates arepository dispatch event that includes a payload containing full details of the command and its context.It also supports creatingworkflow dispatch events with defined input parameters.

"ChatOps" with slash commands can work in a basic way by parsing the commands duringissue_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 newissue_comment eventsand process the commands themselves.

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

An additional benefit of dispatching is that it allows non-sensitive workloads to be run in public repositories to save using private repository GitHub Action minutes.

See it in action with the following live demos.

• ChatOps Demo in Issues
• ChatOps Demo in Pull Requests
• Slash command code formatting - Python

• Getting started
• Examples
• Standard configuration
• Advanced configuration
• Workflow dispatch
• Updating to v4

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 Dispatchon:issue_comment:types:[created]jobs:slashCommandDispatch:runs-on:ubuntu-lateststeps:      -name:Slash Command Dispatchuses:peter-evans/slash-command-dispatch@v4with:token:${{ secrets.PAT }}commands:|            deploy            integration-test            build-docs

Note that not specifying therepository input will mean that dispatch events are created in thecurrent repository by default. It's perfectly fine to use the current repository and not dispatch events to a separate "processor" repository.

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

This action createsrepository_dispatch andworkflow_dispatch events.The defaultGITHUB_TOKEN does not have scopes to create these events, so arepo scopedPAT is required.If you will be dispatching commands to public repositoriesonly then you can use the more limitedpublic_repo scope.

When using the action in a GitHub organization, the user the PAT is created on must be a member of the organization.Additionally, the PAT should be given theorg:read scope.

If you don't specify a token forreaction-token it will use the defaultGITHUB_TOKEN.Reactions to comments will then be made by the @github-actions bot user.You can use aPAT if you would prefer reactions to be made by the user account associated with the PAT.

      -name:Slash Command Dispatchuses:peter-evans/slash-command-dispatch@v4with:token:${{ secrets.PAT }}reaction-token:${{ secrets.PAT }}commands:|            deploy            integration-test            build-docs

This input sets the repository permission level required by the user to dispatch commands.It expects one of thefive repository permission levels, ornone.From the least to greatest permission level they arenone,read,triage,write,maintain andadmin.

Settingwrite as the required permission level means that any user withwrite,maintain oradmin permission level will be able to execute commands.

Note thatread,triage andmaintain are only applicable to organization repositories.For repositories owned by a user account there are only two permission levels, the repository owner (admin) and collaborators (write).

There is a known issue with permissions when usingnested teams in a GitHub organization. Seehere for further details.

By default, the action createsrepository_dispatch events.Settingdispatch-type toworkflow will instead createworkflow_dispatch events.There are significant differences in the action's behaviour when usingworkflow dispatch. Seeworkflow dispatch for usage details.

For the majority of use cases, the defaultrepository dispatch will likely be the most suitable for new workflows.If you already haveworkflow_dispatch workflows, you can execute them with slash commands using this action.

Slash commands must be placed in the first line of the comment to be interpreted as a command.

• The command must start with a/
• The slash command extends to the last non-whitespace character on the first line
• Anything after the first line is ignored and can be freely used for comments

The following documentation applies to thedispatch-type default,repository, which createsrepository_dispatch events.Forworkflow dispatch documentation, seeworkflow dispatch.

Repository dispatch events have atype to distinguish between events. Thetype set by the action is a combination of the slash command andevent-type-suffix. Theevent-type-suffix input defaults to-command.

For example, if your slash command isintegration-test, the event type will beintegration-test-command.

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

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

The slash command context contains the command and any arguments that were supplied by the user.It will also contain any static arguments if configured.

To demonstrate, take the following configuration as an example.

      -uses:peter-evans/slash-command-dispatch@v4with:token:${{ secrets.PAT }}commands:|            deploystatic-args:|            production            region=us-east-1

For the above example configuration, the slash command/deploy branch=main dry-run reason="new feature" will be converted to a JSON payload as follows.

"slash_command": {"command":"deploy","args": {"all":"production region=us-east-1 branch=main dry-run reason=\"new feature\"","unnamed": {"all":"production dry-run","arg1":"production","arg2":"dry-run"            },"named": {"region":"us-east-1","branch":"main","reason":"new feature"            },        }    }

The properties in theslash_command context from the above example can be used in a workflow as follows.

      -name:Output command and argumentsrun:|          echo ${{ github.event.client_payload.slash_command.command }}          echo ${{ github.event.client_payload.slash_command.args.all }}          echo ${{ github.event.client_payload.slash_command.args.unnamed.all }}          echo ${{ github.event.client_payload.slash_command.args.unnamed.arg1 }}          echo ${{ github.event.client_payload.slash_command.args.unnamed.arg2 }}          echo ${{ github.event.client_payload.slash_command.args.named.region }}          echo ${{ github.event.client_payload.slash_command.args.named.branch }}          echo ${{ github.event.client_payload.slash_command.args.named.reason }}          # etc.

The payload contains thegithub context of theissue_comment event at pathgithub.event.client_payload.github.Additionally, if the comment was made in a pull request, the action calls theGitHub API to fetch the pull request detail and attaches it to the payload at pathgithub.event.client_payload.pull_request.

You can inspect the payload with the following step.

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

Note that theclient_payload.github.payload.issue.body andclient_payload.pull_request.body context properties will be truncated if they exceed 1000 characters.

Usingcreate-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 reactionuses:peter-evans/create-or-update-comment@v4with:token:${{ secrets.PAT }}repository:${{ github.event.client_payload.github.payload.repository.full_name }}comment-id:${{ github.event.client_payload.github.payload.comment.id }}reactions:hooray

Another option is to reply with a new comment containing a link to the run output.

      -name:Create URL to the run outputid:varsrun:echo "run-url=https://github.com/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" >> $GITHUB_OUTPUT      -name:Create commentuses:peter-evans/create-or-update-comment@v4with:token:${{ secrets.PAT }}repository:${{ github.event.client_payload.github.payload.repository.full_name }}issue-number:${{ github.event.client_payload.github.payload.issue.number }}body:|            [Command run output][1]            [1]: ${{ steps.vars.outputs.run-url }}

MIT