{"id":13596177,"url":"https://github.com/peter-evans/slash-command-dispatch","last_synced_at":"2025-05-14T15:00:27.342Z","repository":{"id":37870804,"uuid":"223691006","full_name":"peter-evans/slash-command-dispatch","owner":"peter-evans","description":"A GitHub action that facilitates \"ChatOps\" by creating repository dispatch events for slash commands","archived":false,"fork":false,"pushed_at":"2025-05-12T03:56:48.000Z","size":3789,"stargazers_count":628,"open_issues_count":17,"forks_count":56,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-05-12T04:35:13.124Z","etag":null,"topics":["automation","chatops","github-action","repository-dispatch","slash-commands","workflow-queue"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/peter-evans.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"peter-evans"}},"created_at":"2019-11-24T04:14:56.000Z","updated_at":"2025-05-12T03:56:02.000Z","dependencies_parsed_at":"2023-12-04T04:21:27.941Z","dependency_job_id":"9c134623-a93d-4c56-a9c9-9841920242d7","html_url":"https://github.com/peter-evans/slash-command-dispatch","commit_stats":{"total_commits":436,"total_committers":10,"mean_commits":43.6,"dds":0.5435779816513762,"last_synced_commit":"677779695c6c9bada38785b94dedf56629364c6e"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-evans%2Fslash-command-dispatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-evans%2Fslash-command-dispatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-evans%2Fslash-command-dispatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-evans%2Fslash-command-dispatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/peter-evans","download_url":"https://codeload.github.com/peter-evans/slash-command-dispatch/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253678770,"owners_count":21946314,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","chatops","github-action","repository-dispatch","slash-commands","workflow-queue"],"created_at":"2024-08-01T16:02:11.120Z","updated_at":"2025-05-14T15:00:27.302Z","avatar_url":"https://github.com/peter-evans.png","language":"TypeScript","readme":"# Slash Command Dispatch\n[![CI](https://github.com/peter-evans/slash-command-dispatch/workflows/CI/badge.svg)](https://github.com/peter-evans/slash-command-dispatch/actions?query=workflow%3ACI)\n[![GitHub Marketplace](https://img.shields.io/badge/Marketplace-Slash%20Command%20Dispatch-blue.svg?colorA=24292e\u0026colorB=0366d6\u0026style=flat\u0026longCache=true\u0026logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAM6wAADOsB5dZE0gAAABl0RVh0U29mdHdhcmUAd3d3Lmlua3NjYXBlLm9yZ5vuPBoAAAERSURBVCiRhZG/SsMxFEZPfsVJ61jbxaF0cRQRcRJ9hlYn30IHN/+9iquDCOIsblIrOjqKgy5aKoJQj4O3EEtbPwhJbr6Te28CmdSKeqzeqr0YbfVIrTBKakvtOl5dtTkK+v4HfA9PEyBFCY9AGVgCBLaBp1jPAyfAJ/AAdIEG0dNAiyP7+K1qIfMdonZic6+WJoBJvQlvuwDqcXadUuqPA1NKAlexbRTAIMvMOCjTbMwl1LtI/6KWJ5Q6rT6Ht1MA58AX8Apcqqt5r2qhrgAXQC3CZ6i1+KMd9TRu3MvA3aH/fFPnBodb6oe6HM8+lYHrGdRXW8M9bMZtPXUji69lmf5Cmamq7quNLFZXD9Rq7v0Bpc1o/tp0fisAAAAASUVORK5CYII=)](https://github.com/marketplace/actions/slash-command-dispatch)\n\nA GitHub action that facilitates [\"ChatOps\"](https://www.pagerduty.com/blog/what-is-chatops/) by creating dispatch events for slash commands.\n\n### How does it work?\n\nThe action runs in `issue_comment` event workflows and checks the first line of comments for slash commands.\nWhen a valid command is found it creates a [repository dispatch](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#repository_dispatch) event that includes a payload containing full details of the command and its context.\nIt also supports creating [workflow dispatch](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch) events with defined input parameters.\n\n### Why create dispatch events?\n\n\"ChatOps\" with slash commands can work in a basic way by parsing the commands during `issue_comment` events and immediately processing the command.\nIn 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.\n\nDispatching commands to be processed elsewhere keeps the workflow queue moving quickly. It essentially enables parallel processing of workflows.\n\nAn 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.\n\n\u003cdiv align=\"center\"\u003e\u003cimg src=\"docs/assets/slash-command-dispatch.png\" width=\"550\"\u003e\u003c/div\u003e\n\n## Demos\n\nSee it in action with the following live demos.\n\n- [ChatOps Demo in Issues](https://github.com/peter-evans/slash-command-dispatch/issues/3)\n- [ChatOps Demo in Pull Requests](https://github.com/peter-evans/slash-command-dispatch/pull/8)\n- [Slash command code formatting - Python](https://github.com/peter-evans/slash-command-dispatch/pull/28)\n\n## Documentation\n\n- [Getting started](docs/getting-started.md)\n- [Examples](docs/examples.md)\n- [Standard configuration](#standard-configuration)\n- [Advanced configuration](docs/advanced-configuration.md)\n- [Workflow dispatch](docs/workflow-dispatch.md)\n- [Updating to v4](docs/updating.md)\n\n## Dispatching commands\n\n### Standard configuration\n\nThe 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`.\n\n```yml\nname: Slash Command Dispatch\non:\n  issue_comment:\n    types: [created]\njobs:\n  slashCommandDispatch:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Slash Command Dispatch\n        uses: peter-evans/slash-command-dispatch@v4\n        with:\n          token: ${{ secrets.PAT }}\n          commands: |\n            deploy\n            integration-test\n            build-docs\n```\n\nNote that not specifying the `repository` input will mean that dispatch events are created in the *current* repository by default. It's perfectly fine to use the current repository and not dispatch events to a separate \"processor\" repository.\n\nThis action also features [advanced configuration](docs/advanced-configuration.md) that allows each command to be configured individually if necessary. Use the standard configuration shown above unless you require advanced features.\n\n### Action inputs\n\n| Input | Description | Default |\n| --- | --- | --- |\n| `token` | (**required**) A `repo` scoped [Personal Access Token (PAT)](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token). Note: `GITHUB_TOKEN` *does not* work here. See [token](#token) for further details. | |\n| `reaction-token` | `GITHUB_TOKEN` or a `repo` scoped [Personal Access Token (PAT)](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token). See [reaction-token](#reaction-token) for further details. | `GITHUB_TOKEN` |\n| `reactions` | Add reactions. :eyes: = seen, :rocket: = dispatched | `true` |\n| `commands` | (**required**) A comma or newline separated list of commands. | |\n| `permission` | The repository permission level required by the user to dispatch commands. See [permission](#permission) for further details. (`none`, `read`, `triage`, `write`, `maintain`, `admin`) | `write` |\n| `issue-type` | The issue type required for commands. (`issue`, `pull-request`, `both`) | `both` |\n| `allow-edits` | Allow edited comments to trigger command dispatches. | `false` |\n| `repository` | The full name of the repository to send the dispatch events. | Current repository |\n| `event-type-suffix` | The repository dispatch event type suffix for the commands. | `-command` |\n| `static-args` | A comma or newline separated list of arguments that will be dispatched with every command. | |\n| `dispatch-type` | The dispatch type; `repository` or `workflow`. See [dispatch-type](#dispatch-type) for further details. | `repository` |\n| `config` | | JSON configuration for commands. See [Advanced configuration](docs/advanced-configuration.md) | |\n| `config-from-file` | | JSON configuration from a file for commands. See [Advanced configuration](docs/advanced-configuration.md) | |\n\n#### `token`\n\nThis action creates [repository_dispatch](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#repository_dispatch) and [workflow_dispatch](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch) events.\nThe default `GITHUB_TOKEN` does not have scopes to create these events, so a `repo` scoped [PAT](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) is required.\nIf you will be dispatching commands to public repositories *only* then you can use the more limited `public_repo` scope.\n\nWhen using the action in a GitHub organization, the user the PAT is created on must be a member of the organization.\nAdditionally, the PAT should be given the `org:read` scope.\n\n#### `reaction-token`\n\nIf you don't specify a token for `reaction-token` it will use the default `GITHUB_TOKEN`.\nReactions to comments will then be made by the @github-actions bot user.\nYou can use a [PAT](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) if you would prefer reactions to be made by the user account associated with the PAT. \n\n```yml\n      - name: Slash Command Dispatch\n        uses: peter-evans/slash-command-dispatch@v4\n        with:\n          token: ${{ secrets.PAT }}\n          reaction-token: ${{ secrets.PAT }}\n          commands: |\n            deploy\n            integration-test\n            build-docs\n```\n\n#### `permission`\n\nThis input sets the repository permission level required by the user to dispatch commands.\nIt expects one of the [five repository permission levels](https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization#permission-levels-for-repositories-owned-by-an-organization), or `none`.\nFrom the least to greatest permission level they are `none`, `read`, `triage`, `write`, `maintain` and `admin`.\n\nSetting `write` as the required permission level means that any user with `write`, `maintain` or `admin` permission level will be able to execute commands.\n\nNote that `read`, `triage` and `maintain` are only applicable to organization repositories.\nFor repositories owned by a user account there are only two permission levels, the repository owner (`admin`) and collaborators (`write`).\n\nThere is a known issue with permissions when using [nested teams](https://docs.github.com/en/organizations/organizing-members-into-teams/about-teams#nested-teams) in a GitHub organization. See [here](https://github.com/peter-evans/slash-command-dispatch/issues/120) for further details.\n\n#### `dispatch-type`\n\nBy default, the action creates [repository_dispatch](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#repository_dispatch) events.\nSetting `dispatch-type` to `workflow` will instead create [workflow_dispatch](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch) events.\nThere are significant differences in the action's behaviour when using `workflow` dispatch. See [workflow dispatch](docs/workflow-dispatch.md) for usage details.\n\nFor the majority of use cases, the default `repository` dispatch will likely be the most suitable for new workflows.\nIf you already have `workflow_dispatch` workflows, you can execute them with slash commands using this action.\n\n| Repository Dispatch (default) | Workflow Dispatch |\n| --- | --- |\n| Events are created with a `client_payload` giving the target workflow access to a wealth of useful [context properties](#accessing-contexts). | A `client_payload` cannot be sent with [workflow_dispatch](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch) events. The target workflow can only make use of up to 10 pre-defined inputs, the names of which must match named arguments supplied with the slash command. |\n| Slash commands can only execute workflows in the target repository's default branch. | Slash commands can execute workflows in any branch using the `ref` named argument. The reference can be a branch, tag, or a commit SHA. This can be useful to test workflows in PR branches before merging. |\n| Immediate command validation feedback is unavailable when creating the dispatch event. | Immediate command [validation feedback](docs/workflow-dispatch.md#validation-errors) is available as an action output. |\n\n### How comments are parsed for slash commands\n\nSlash commands must be placed in the first line of the comment to be interpreted as a command.\n\n- The command must start with a `/`\n- The slash command extends to the last non-whitespace character on the first line\n- Anything after the first line is ignored and can be freely used for comments\n\n![Comment Parsing](docs/assets/comment-parsing.png)\n\n## Handling dispatched commands\n\nThe following documentation applies to the `dispatch-type` default, `repository`, which creates [repository_dispatch](https://developer.github.com/v3/repos/#create-a-repository-dispatch-event) events.\nFor `workflow` dispatch documentation, see [workflow dispatch](docs/workflow-dispatch.md).\n\n### Event types\n\nRepository 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`.\n\nFor example, if your slash command is `integration-test`, the event type will be `integration-test-command`.\n\n```yml\non:\n  repository_dispatch:\n    types: [integration-test-command]\n```\n\n### Accessing contexts\n\nCommands are dispatched with a payload containing a number of contexts.\n\n#### `slash_command` context\n\nThe slash command context contains the command and any arguments that were supplied by the user.\nIt will also contain any static arguments if configured.\n\nTo demonstrate, take the following configuration as an example.\n```yml\n      - uses: peter-evans/slash-command-dispatch@v4\n        with:\n          token: ${{ secrets.PAT }}\n          commands: |\n            deploy\n          static-args: |\n            production\n            region=us-east-1\n```\n\nFor the above example configuration, the slash command `/deploy branch=main dry-run reason=\"new feature\"` will be converted to a JSON payload as follows.\n\n```json\n    \"slash_command\": {\n        \"command\": \"deploy\",\n        \"args\": {\n            \"all\": \"production region=us-east-1 branch=main dry-run reason=\\\"new feature\\\"\",\n            \"unnamed\": {\n                \"all\": \"production dry-run\",\n                \"arg1\": \"production\",\n                \"arg2\": \"dry-run\"\n            },\n            \"named\": {\n                \"region\": \"us-east-1\",\n                \"branch\": \"main\",\n                \"reason\": \"new feature\"\n            },\n        }\n    }\n```\n\nThe properties in the `slash_command` context from the above example can be used in a workflow as follows.\n\n```yml\n      - name: Output command and arguments\n        run: |\n          echo ${{ github.event.client_payload.slash_command.command }}\n          echo ${{ github.event.client_payload.slash_command.args.all }}\n          echo ${{ github.event.client_payload.slash_command.args.unnamed.all }}\n          echo ${{ github.event.client_payload.slash_command.args.unnamed.arg1 }}\n          echo ${{ github.event.client_payload.slash_command.args.unnamed.arg2 }}\n          echo ${{ github.event.client_payload.slash_command.args.named.region }}\n          echo ${{ github.event.client_payload.slash_command.args.named.branch }}\n          echo ${{ github.event.client_payload.slash_command.args.named.reason }}\n          # etc.\n```\n\n#### `github` and `pull_request` contexts\n\nThe payload contains the `github` context of the `issue_comment` event at path `github.event.client_payload.github`.\nAdditionally, if the comment was made in a pull request, the action calls the [GitHub API to fetch the pull request detail](https://docs.github.com/en/rest/pulls/pulls#get-a-pull-request) and attaches it to the payload at path `github.event.client_payload.pull_request`.\n\nYou can inspect the payload with the following step.\n```yml\n      - name: Dump the client payload context\n        env:\n          PAYLOAD_CONTEXT: ${{ toJson(github.event.client_payload) }}\n        run: echo \"$PAYLOAD_CONTEXT\"\n```\n\nNote that the `client_payload.github.payload.issue.body` and `client_payload.pull_request.body` context properties will be truncated if they exceed 1000 characters.\n\n### Responding to the comment on command completion\n\nUsing [create-or-update-comment](https://github.com/peter-evans/create-or-update-comment) action there are a number of ways you can respond to the comment once the command has completed.\n\nThe simplest response is to add a :tada: reaction to the comment.\n\n```yml\n      - name: Add reaction\n        uses: peter-evans/create-or-update-comment@v4\n        with:\n          token: ${{ secrets.PAT }}\n          repository: ${{ github.event.client_payload.github.payload.repository.full_name }}\n          comment-id: ${{ github.event.client_payload.github.payload.comment.id }}\n          reactions: hooray\n```\n\nAnother option is to reply with a new comment containing a link to the run output.\n\n```yml\n      - name: Create URL to the run output\n        id: vars\n        run: echo \"run-url=https://github.com/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID\" \u003e\u003e $GITHUB_OUTPUT\n\n      - name: Create comment\n        uses: peter-evans/create-or-update-comment@v4\n        with:\n          token: ${{ secrets.PAT }}\n          repository: ${{ github.event.client_payload.github.payload.repository.full_name }}\n          issue-number: ${{ github.event.client_payload.github.payload.issue.number }}\n          body: |\n            [Command run output][1]\n\n            [1]: ${{ steps.vars.outputs.run-url }}\n```\n\n## License\n\n[MIT](LICENSE)\n","funding_links":["https://github.com/sponsors/peter-evans"],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeter-evans%2Fslash-command-dispatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeter-evans%2Fslash-command-dispatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeter-evans%2Fslash-command-dispatch/lists"}