This action allows you to add comments, reviewers and assignees to a pull request depending on rules you define!

• What is use-herald-action?
  • Motivation
• How to create a rule
• Rule Examples
• Input parameters
• Output
• Examples
  • Basic example
  • Using output

Given a set of rules defined in a JSON document, this action will execute actions based on those rules.

A rule is a way of defining an action that is to be performed once a certain set of conditions is met. For example, you might want to get notified every time somebody opens a pull request that affects some file you're interested in, even if they didn't add you as a reviewer and you are not a codeowner.

Working with a more concrete example, we have the power to create a rule that:

• Has conditions:
  • { pull_request title contains node}
  • { files matching *.ts are changed }
• If all conditions met, will take the action:
  • notify me

One way to think about these rules is to compare it to mail filters (Gmail filters) that will, for example, apply labels to incoming mail if certain keywords are found in the subject or body. In this context, we are dealing with pull requests instead of emails.

This action is particularly useful when you want to subscribe to changes made to certain files, much like the "Subscriber" concept used in Phabricator.

For attaching reviewers, GitHub offers CODEOWNERS. However, no equivalent exists for assigning users. Nor does there exist a method to automatically subscribe to said pull requests (without being a reviewer).

Although the main motivation behind this GitHub Action is to bridge the gap described above, this can be extended to many different use cases.

Every rule can be written in JSON with the following key-value pairs:

Notify users @eeny, @meeny, @miny and @moe when all files matching *.ts are changed

{
  "users": ["@eeny", "@meeny", "@miny", "@moe"],
  "action": "comment",
  "includes": "*.ts"
}

Notify team @myTeam when files matching directory/*.js are changed, excluding directory/notThisFile.js

{
  "teams": ["@myTeam"],
  "action": "comment",
  "includes": "directory/*.ts",
  "excludes": "directory/notThisFile.js"
}

Assign team @QATeam when files matching integration/*.js are changed and the title of the pull request includes QA

{
  "teams": ["@QATeam"],
  "action": "assign",
  "includes": "integration/*.ts",
  "eventJSONPath": "$[?(@.title =~ /QA/)].title"
}

This action will store the rules applied in outputs.appliedRules. Here, you will find the matching rules, grouped by actions (comment | assign | review).

Note that you will have to parse the output using the fromJSON function before accessing individual properties. See the Using Output example for more details.

This step runs the action without regard for output:

- name: Apply Herald rules
  uses: gagoar/use-herald-action@master
  with:
    GITHUB_ACTION: ${{ secrets.GITHUB_ACTION }}
    rulesLocation: 'rules/*.json'
    dryRun: true

These steps stores the action's outputs into a JSON file:

- name: Apply Herald rules
  uses: gagoar/use-herald-action@master
  id: foobar
  with:
    GITHUB_ACTION: ${{ secrets.GITHUB_ACTION }}
    rulesLocation: 'rules/*.json'
    dryRun: true
- name: Store applied rules to file
  run: echo '\${{ fromJSON(steps.foobar.outputs.appliedRules) }}' > rulesApplied.json

Notice the inclusion of the id field in the first step (Invoke foobarFunction Lambda). This is so that the second step (Store response payload to file) can reference the result of the first step. For more information for Github Actions outputs, see their reference.