interactive event dispatcher

This GitHub Action is an effort to correct various shortcomings of the default GitHub action and event system.

What are these shortcomings?

1. GitHub's events don't distinguish between issue comments and pull requests comments.
2. pull_request_target is not made to check forks. The token of this event's context has full permissions.
3. Different events use different context descriptors for the same attributes (e.g., pull request number vs. issue number).
4. Events don't have an integrated permission filter.
5. Pull request actions always run without any previous user interaction.

How does this action solve this?

This action analyzes the source events based on the maintainer's preferences and conditionally dispatches a custom event. The event includes a unified source event payload where possible. The action is able to differentiate permission levels of issues and pull requests, as well as comments. It is also able to parse comments for user commands and conditionally forward them to a single or dynamic target event. Pull request events can be delayed until a collaborator checks it for security breaches. The checks for the triggered events are automatically added to the source event reference.

Inputs

actionsToken

**WARNING:** Do not change this! It will be used for API requests that only the default token can perform.

affiliation

Collaborators are determined by the given affiliation status. Can be either of direct, outside, or all. Outside collaborators and unaffiliated outsiders are different things. outside defines collaborators who are not part of your organization.

appendCommand

By default, this action always triggers the same output event type as defined in prefixFilter. The type name can be extended by the determined command name.

Example

event: dispatched
prefixFilter: '[$]action(s?)'
commandFilter: \|
  publish docs
  publish release
appendCommand: true

Comment

$actions publish docs

The triggered event type will be dispatched\_publish\_docs.

commandFilter

Besides the prefix, comments can further be filtered for their commands. If enabled, only the given command expressions are accpeted for events to trigger. The filter accepts regular expression syntax. The input is enabled if any non-zero value is set. A list can be set via a line separation.

event

This input defines the type name of the repository\_dispatch event to trigger.

outsiderCommands

By default, comments will only be accepted and dispatched if they originate from collaborators of the repository. This behavior can be extended to all users, regardless of affiliation status, by enabling this input.

perPage

For repositories with frequent and large numbers of comments or workflows, the API might not return all nodes for all requests. That is because not every endpoint provides the appropriate filtering methods. This input can compensate for this limitation. It can be set up to 100.

**Recommendation:** Leave this parameter untouched unless checks are missing in the commit reference.

prefixFilter

Incoming comment events can be filtered by their content. This input enables a filter for trigger events to contain the given prefix to be matched. If enabled, the suffix of this prefix will be passed as outputs.command and as github.event.client\_payload.command to the target event. The filter accepts regular expression syntax. This input is enabled if any non-empty value is set.

Example

prefixFilter: '[$]action(s?)'

Comment

$action publish something

The determined command will be publish something.

pullMode

**WARNING:** Do not disable this for target workflows that execute code or tests on pull requests. By default, pull requests events are checked for the author's affiliation status. If the author is not affiliated, they will receive a friendly comment that notifies them that not all checks can be run yet until a collaborator's approval. Collaborators can then check the pull request and approve a specific commit by commenting a command or by using an action button provided by the check itself that approves the most recent commit.

If disabled, this action will skip the affiliation check and always forward events from any source (i.e. pull requests and issues). Check commands will not be processed.

token

A repository-scoped personal access token is necessary for API access. The default GitHub token will not work because events from this token are ignored by GitHub's event controller.

Outputs

command

If inputs.prefixFilter is enabled, this output contains the matched subsequent command of a filtered command comment.

triggered

If inputs.prefixFilter is enabled, only true if the prefix was matched, otherwise always true.

typeName

This output depicts the event's action type name that is triggered.

Example

This is an example that includes all typical inputs.