chocrates / stop-action-filter

Stops the running action if the filter criteria is met

GitHub Action - stop-action-filter

This GitHub Action is intended to replace repeated if statements within a workflow file, by allowing the user to cancel an action based on attributes of the GitHub context that is generated on the event.
It utilizes PegJS to generate a simple filter language that allows you to traverse the context and validate that attributes match what you are looking for.

Usage

Pre-requisites

Generate a Personal Access Token and save it in your secrets for the Repo that you wish to use this action.

Inputs

• FILTER: This is the filter that is used validate the GitHub context. When it evaluates to True the action exits and your workflow continues on. When it evaluates to False the action will utilize the Actions API to cancel the current workflow

Environment Variables

• GITHUB_TOKEN: This is the PAT that you generated earlier. This is used to call the Actions API to cancel the current workflow run

Filter Grammer

Currently the grammer is quite simple. You can have a string, surrounded by single or double quotes, or a path to a property within the GitHub Context. Paths and Strings can be compared with the standard boolean operators, <, <=, >, >=, ==.
Additionally you can validate that a property is in a list of strings using the in operator (examples below). Finally there is a not operator, ! that can be prepended to the command group to negate the result. Commands can be chained with || and &&. Currently the grammer does not support operator precedence and will combine commands together in order from left to right. Command grouping with parenthesis is not currently implemented, but it is on the wishlist (PR's welcome!)

Paths

Paths use the standard javascript dot notation, so to get the issue number of an issue you would have a path like so: payload.issue.number

Strings

Strings are any group of text surrounded by a single or double quotes. Anything else will be assumed to be a path

In expressions

in lets you validate that a property is one of a list of strings like so payload.label.name in ['bug','documentation'].
Temporarily we also will check the labels object for their names, so if you want to make sure that your issue is labeled with a certain label, you can write a filter like this payload.issue.labels in ["bug","documentation"] This is will be further fleshed out once we implement full object comparison.

Example Filters

• Filter the issue labeled event to only bug or question
  • payload.label.name in [ 'bug', 'question' ]
• Filter the comment created event to a certain user
  • payload.comment.user.login == "Chocrates"

Example Workflow

• When a user opens a new bug leave them a comment with next steps and links to other resources to get help

name: Test workflow to add a comment to bugs
on:
  issues:
    types: [labeled]

jobs:
  add-comment:
    runs-on: ubuntu-latest
    steps:
      - uses: chocrates/stop-action-filter@master
        with:
          filter: 'payload.issue.labels in ["bug"]'
        env:
          GITHUB_TOKEN: ${{ secrets.TOKEN }}
      - uses: ActionsDesk/add-comment-action@release/v1
        with:
          message: 'Thank you for opening an issue!  I am sorry you are having troubles.  While you wait for your issue to get Triaged, please consider glancing at the documentation in the wiki: https://github.com/Chocrates/stop-action-filter/wiki'
          stepStatus: 'success'
        env:
          GITHUB_TOKEN: ${{ secrets.TOKEN }}

Contributing

Please submit PR's for patches you would like to see merged into the mainline. If you have any questions or would like some help with please open an issue. When submitting PR's please make sure you have added tests covering the new functionality.

License

All code and documentation are released under the MIT License

stop-action-filter's Issues

Implement object comparison

Need to determine a good pattern for validating objects within the context rather than forcing the user to check individual properties

Implement Date comparisons

Add a new type to the grammar to allow date comparisons. We want to get to a point where we can write a filter that would exclude/include events based on when the object was updated.
For instance if an "old" issue has a new comment we could respond to the comment and close the issue as stale.

Formally document the grammar

The parser was scraped together from various example grammars out there to get us to a state that it is usable. Would be great to formally document the grammar (possibly including enhancements that are seen fit) so we can understand where we want to get the filter language to.

Implement `!=` expression

For some reason != was left out of the initial set of expressions you can use to compare the left and right side.
https://github.com/Chocrates/stop-action-filter/blob/master/src/parser.pegjs#L53

Implement Parenthesis Grouping

Currently the filters are interpreted left to right when there are more than one commands

It would be great to be able to implement operator precedence with parenthesis grouping like most all programing languages.

I am a new test bug

Test Issue