Use Herald Action

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

The following documentation is also available at our GitHub Pages site.

Table of contents

• Use Herald Action
  • Table of contents
  • What is use-herald-action?
  • Motivation
  • Additional setup
  • Context
  • How to create a rule
  • Rule Examples
  • Error levels
  • Input parameters
  • Output
  • Events
  • Examples
  • Basic example
  • Using output

What is use-herald-action?

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.

Motivation

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.

Additional setup

Are you looking to use use-herald-action in a private organization's repository? If so, you will need to do some additional setup here prior to using the action in your workflow.

Context

The secret secrets.GITHUB_TOKEN provided in a workflow does not have sufficient permissions to mention users and teams that belong to private organizations. This is a problem because use-herald-action will create a comment with mentions of private users and teams (prepended with an @), but Github will not notify the users because of the lack of permissions. To solve this, we generate a token with sufficient permissions by installing a GitHub App in your private organization. For more information, see this issue.

How to create a rule

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

Rule Examples

*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/.jsare changed, excludingdirectory/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.match("QA"))]"
}

*Add a comment on a pull request when files matching `directory/.jsare changed, excludingdirectory/notThisFile.js`**

{
  "action": "comment",
  "includes": "directory/*.ts",
  "excludes": "directory/notThisFile.js",
  "customMessage": "Thank you for making changes to directory/*.ts. Please make sure your pull request follows the contribution guidelines of [myTeam]"
}

Error levels

When creating rules, you can use the errorLevel to change how use-herald-action will report back when the rule has no matches. This could be useful to make sure a rule is always matching. For example, when trying to validate that a pull request template is respected.

Add friendly message when a PR is opened, but if is not applied, fail the workflow

{
  "action": "comment",
  "customMessage": "Thanks for opening a pull request, looks like all is good! Please wait till the checks are all green to merge ",
  "eventJsonPath": "$..[?(@.body.match("Issue Ticket:"))]",
  "errorLevel": "error"
}

Input parameters

Output

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.

Events

Use herald action can only be used on the following events:

• pull_request
• pull_request_target
• push

Any other event will produce an error in the workflow

Examples

Basic example

This step runs the action without regard for output:

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

If you are looking for some examples you can take a look at this workflow. You can also find some examples on herald rules here

Using output

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_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    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.