{"id":13529992,"url":"https://github.com/gagoar/use-herald-action","last_synced_at":"2025-04-06T09:09:08.359Z","repository":{"id":37023712,"uuid":"277407349","full_name":"gagoar/use-herald-action","owner":"gagoar","description":"GitHub action to add reviewers, subscribers, labels, and assignees to your PR. You can validate your PR template as well. ","archived":false,"fork":false,"pushed_at":"2025-02-10T20:46:55.000Z","size":5087,"stargazers_count":56,"open_issues_count":36,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-30T08:08:51.208Z","etag":null,"topics":["assignees","herald","labels","pull-request-action","reviewers","validation"],"latest_commit_sha":null,"homepage":"https://gagoar.github.io/use-herald-action/","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/gagoar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"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}},"created_at":"2020-07-06T00:32:36.000Z","updated_at":"2025-03-23T18:35:25.000Z","dependencies_parsed_at":"2023-12-07T16:47:03.326Z","dependency_job_id":"7404adda-71d0-4ed9-9395-dd2d7385e0ee","html_url":"https://github.com/gagoar/use-herald-action","commit_stats":{"total_commits":447,"total_committers":9,"mean_commits":"49.666666666666664","dds":"0.18791946308724827","last_synced_commit":"6dedc43fd3b30d93cd2ca2985d6ac0d25f6a898b"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gagoar%2Fuse-herald-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gagoar%2Fuse-herald-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gagoar%2Fuse-herald-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gagoar%2Fuse-herald-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gagoar","download_url":"https://codeload.github.com/gagoar/use-herald-action/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247457802,"owners_count":20941906,"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":["assignees","herald","labels","pull-request-action","reviewers","validation"],"created_at":"2024-08-01T07:00:41.818Z","updated_at":"2025-04-06T09:09:08.332Z","avatar_url":"https://github.com/gagoar.png","language":"TypeScript","funding_links":[],"categories":["Community Resources"],"sub_categories":["GitHub Tools and Management"],"readme":"\u003cp align=\"center\"\u003e\n \u003ca href=\"https://github.com/marketplace/actions/use-herald-action\"\u003e\n \u003cimg src=\"https://img.shields.io/badge/Marketplace-v2-undefined.svg?logo=github\u0026logoColor=white\u0026style=flat\" alt=\"GitHub Marketplace\" /\u003e\n \u003c/a\u003e\n \u003ca href=\"https://github.com/gagoar/use-herald-action/actions\"\u003e\n \u003cimg src=\"https://github.com/gagoar/use-herald-action/workflows/validation%20on%20Master/badge.svg\" alt=\"Workflow\" /\u003e\n \u003c/a\u003e\n \u003ca href=\"https://codecov.io/gh/gagoar/use-herald-action\"\u003e\n \u003cimg src=\"https://codecov.io/gh/gagoar/use-herald-action/branch/master/graph/badge.svg?token=48gHuQl8zV\" alt=\"codecov\" /\u003e\n \u003c/a\u003e\n \u003ca href=\"https://github.com/gagoar/alohomora/blob/master/LICENSE\"\u003e\n \u003cimg src=\"https://img.shields.io/npm/l/alohomora.svg?style=flat-square\" alt=\"MIT license\" /\u003e\n \u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n \u003ca href=\"https://github.com/gagoar/use-herald-action\"\u003e\n \u003cimg src=\"images/logo.png\" alt=\"Logo\" width=\"128\" height=\"128\"\u003e\n \u003c/a\u003e\n\n \u003c/p\u003e\n\n# Use Herald Action\n\nThis action allows you to add comments, reviewers and assignees to a pull request depending on rules you define!\n\nThe following documentation is also available at our [GitHub Pages site](https://gagoar.github.io/use-herald-action/).\n\n## Table of contents\n\n- [Use Herald Action](#use-herald-action)\n - [Table of contents](#table-of-contents)\n - [What is `use-herald-action`?](#what-is-use-herald-action)\n - [Motivation](#motivation)\n - [Additional setup](#additional-setup)\n - [Context](#context)\n - [How to create a rule](#how-to-create-a-rule)\n - [Rule Examples](#rule-examples)\n - [Error levels](#error-levels)\n - [Input parameters](#input-parameters)\n - [Output](#output)\n - [Events](#events)\n - [Examples](#examples)\n - [Basic example](#basic-example)\n - [Using output](#using-output)\n\n\u003chr\u003e\n\n## What is `use-herald-action`?\n\nGiven a set of rules defined in a JSON document, this action will execute actions based on those rules.\n\nA **rule** is a way of defining an action that is to be performed once a certain set of conditions is met.\nFor 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](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners).\n\nWorking with a more concrete example, we have the power to create a rule that:\n\n- Has conditions:\n - { `pull_request` `title` contains `node`}\n - { files matching `*.ts` are changed }\n- If all conditions met, will take the action:\n - `notify me`\n\nOne way to think about these rules is to compare it to mail filters ([Gmail filters](https://support.google.com/mail/answer/6579)) that will, for example, apply labels to incoming mail if certain keywords are found in the subject or body.\nIn this context, we are dealing with pull requests instead of emails.\n\n### Motivation\n\nThis action is particularly useful when you want to subscribe to changes made to certain files, much like the \"Subscriber\" concept used in [Phabricator](https://www.phacility.com/phabricator/).\n\nFor attaching reviewers, GitHub offers [CODEOWNERS](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners).\nHowever, no equivalent exists for [assigning](https://docs.github.com/en/github/managing-your-work-on-github/assigning-issues-and-pull-requests-to-other-github-users) users.\nNor does there exist a method to automatically subscribe to said pull requests (without being a reviewer).\n\nAlthough the main motivation behind this GitHub Action is to bridge the gap described above, this can be extended to many different use cases.\n\n\u003chr\u003e\n\n## Additional setup\n\nAre you looking to use `use-herald-action` in a **private organization's repository**? If so, you will need to do some [additional setup here](https://gagoar.github.io/use-herald-action/organization-app-flow/) prior to using the action in your workflow.\n\n### Context\n\nThe 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](https://github.com/gagoar/use-herald-action/issues/83).\n\n\u003chr\u003e\n\n## How to create a rule\n\nEvery rule can be written in JSON with the following key-value pairs:\n\n| Key | Type | Required | Description |\n| ----------------- | :--------------------: | :------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `name` | `string` | No | Friendly name to recognize the rule; defaults to the rule filename |\n| `description` | `string` | No | Description for a rule; It will be used when `action` is set to `status` as the description for the [commit status](https://github.blog/2012-09-04-commit-status-api/) or when `action` is set to `comment` |\n| `action` | `string` | Yes | Currently, supported actions are [comment](https://docs.github.com/en/enterprise/2.14/user/articles/commenting-on-a-pull-request), [review](https://docs.github.com/en/enterprise/2.15/user/articles/requesting-a-pull-request-review#:~:text=Under%20your%20repository%20name%2C%20click,to%20their%20username%2C%20click%20Request), [assign](https://docs.github.com/en/enterprise/2.13/user/articles/assigning-issues-and-pull-requests-to-other-github-users#:~:text=Under%20your%20repository%20name%2C%20click,their%20name%20when%20it%20appears) and [label](https://docs.github.com/en/github/managing-your-work-on-github/applying-labels-to-issues-and-pull-requests), [status](https://github.blog/2012-09-04-commit-status-api/) |\n| `includes` | `string` \\| `string[]` | No | Glob pattern/s used to match changed filenames in the pull request |\n| `excludes` | `string` \\| `string[]` | No | Glob pattern/s used to exclude changed filenames (requires `includes` key to be provided) |\n| `eventJsonPath` | `string` \\| `string[]` | No | [JsonPath expressions](https://goessner.net/articles/JsonPath/) used to filter information in the [pull request event](https://developer.github.com/webhooks/event-payloads/#pull_request). Rules will be evaluated in order as they appear in the array |\n| `includesInPatch` | `string` \\| `string[]` | No | Regex to match file content changes (ignored if malformed or invalid) |\n| `customMessage` | `string` | No | Message to be commented on the pull request when the rule is applied (requires `action === comment`) |\n| `users` | `string[]` | No | GitHub user handles (or emails) on which the rule will take action. It will not be used when `action` is set to `comment` and `customMessage` field is present |\n| `teams` | `string[]` | No | GitHub teams on which the rule will take action. It will not be used when `action` is set to `comment` and `customMessage` field is present |\n| `targetURL` | `string` | No | When `action` set to `status`, link to which the [Details](https://github.blog/2012-09-04-commit-status-api/) link will point |\n| `labels` | `string[]` | No | Github labels which the rule will add. Only valid when `action` field is set to `label` |\n| `errorLevel` | `string` | No | Currently, supported error levels are `none`, `error`, by default is set to `none`, you can read more [here](#error-levels) |\n\n## Rule Examples\n\n**Notify users @eeny, @meeny, @miny and @moe when all files matching `*.ts` are changed**\n\n```json\n{\n \"users\": [\"eeny\", \"meeny\", \"miny\", \"moe\"],\n \"action\": \"comment\",\n \"includes\": \"*.ts\"\n}\n```\n\n**Notify team @myTeam when files matching `directory/*.js` are changed, excluding `directory/notThisFile.js`**\n\n```json\n{\n \"teams\": [\"myTeam\"],\n \"action\": \"comment\",\n \"includes\": \"directory/*.ts\",\n \"excludes\": \"directory/notThisFile.js\"\n}\n```\n\n**Assign team @QATeam when files matching `integration/*.js` are changed and the title of the pull request includes QA**\n\n```json\n{\n \"teams\": [\"QATeam\"],\n \"action\": \"assign\",\n \"includes\": \"integration/*.ts\",\n \"eventJsonPath\": \"$..[?(@.title.match(\"QA\"))]\"\n}\n```\n\n**Add a comment on a pull request when files matching `directory/*.js` are changed, excluding `directory/notThisFile.js`**\n\n```json\n{\n \"action\": \"comment\",\n \"includes\": \"directory/*.ts\",\n \"excludes\": \"directory/notThisFile.js\",\n \"customMessage\": \"Thank you for making changes to directory/*.ts. Please make sure your pull request follows the contribution guidelines of [myTeam]\"\n}\n```\n\n## Error levels\n\nWhen 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.\n\n**Add friendly message when a PR is opened, but if is not applied, fail the workflow**\n\n```json\n{\n \"action\": \"comment\",\n \"customMessage\": \"Thanks for opening a pull request, looks like all is good! Please wait till the checks are all green to merge \",\n \"eventJsonPath\": \"$..[?(@.body.match(\"Issue Ticket:\"))]\",\n \"errorLevel\": \"error\"\n}\n```\n\n## Input parameters\n\n| Key | Type | Required | Description |\n| --------------- | :-------: | :------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `GITHUB_TOKEN` | `string` | Yes | [GitHub token](https://docs.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token#using-the-github_token-in-a-workflow), necessary for adding reviewers, assignees or comments on the PR |\n| `rulesLocation` | `string` | Yes | Directory where the rules can be found |\n| `base` | `string` | No | Fixed base - tag/branch against which to always compare changes (more info on [base](https://docs.github.com/en/github/committing-changes-to-your-project/comparing-commits) |\n| `DEBUG` | `string` | No | Provide to enable verbose logging (ex: `DEBUG: \"*\"`) |\n| `dryRun` | `boolean` | No | Evaluate rule conditions but do not execute actions - [see output for results](#output) |\n\n\u003chr\u003e\n\n## Output\n\nThis action will store the rules applied in `outputs.appliedRules`.\nHere, you will find the matching rules, grouped by actions (`comment | assign | review`).\n\nNote that you will have to parse the output using the [`fromJSON` function](https://help.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#functions) before accessing individual properties.\nSee the [Using Output](#Using-Output) example for more details.\n\n\u003chr\u003e\n\n## Events\n\nUse herald action can only be used on the following events:\n\n- `pull_request`\n- `pull_request_target`\n- `push`\n\nAny other event will produce an error in the workflow\n\n## Examples\n\n### Basic example\n\nThis step runs the action without regard for output:\n\n```yaml\n- name: Apply Herald rules\n uses: gagoar/use-herald-action@master\n with:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n rulesLocation: 'rules/*.json'\n```\n\nIf you are looking for some examples you can take a look at [this workflow](https://github.com/gagoar/use-herald-action/blob/5c4fffb830e2b39c7e9c5f56f9e1d84bac5c9621/.github/workflows/use_action.yml). You can also find some examples on herald rules [here](https://github.com/gagoar/use-herald-action/tree/5c4fffb830e2b39c7e9c5f56f9e1d84bac5c9621/herald_rules)\n\n### Using output\n\nThese steps stores the action's outputs into a JSON file:\n\n```yaml\n- name: Apply Herald rules\n uses: gagoar/use-herald-action@master\n id: foobar\n with:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n rulesLocation: 'rules/*.json'\n dryRun: true\n- name: Store applied rules to file\n run: echo '\\${{ fromJSON(steps.foobar.outputs.appliedRules) }}' \u003e rulesApplied.json\n```\n\nNotice 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.\nFor more information for Github Actions outputs, see their [reference](https://help.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjobs_idoutputs).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgagoar%2Fuse-herald-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgagoar%2Fuse-herald-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgagoar%2Fuse-herald-action/lists"}