/set-assignee-reviewer-when-ready

A GitHub Action to set assignee(s) or reviewer(s) when a PR has finished all checks.

Primary LanguageTypeScriptMIT LicenseMIT

Set Assignee Reviewer when Ready

A GitHub Action to set assignee(s) or reviewer(s) when a PR has finished all checks.

Want to get notified about a PR before the checks have completed?

No? I don't either.

GitHub Marketplace GitHub Marketplace GitHub Marketplace

Why?

This GitHub action was created because Dependabot only provides the ability to either:

  • Set assignees and/or reviewers upon Dependabot PR creation.
  • Not set assignees or reviewers on Dependabot PRs.

This action is intended to allow users to have reviews requested (or, assigned) on PRs once one or more of the required checks ends in an 'unacceptable' state (ie, it failed, or timed out). A good use-case / example of this is Dependabot PRs which you might have configured to auto-merge, and only want to be notified (via being requested for reviews) when a required check has failed. This GitHub Action provides various configuration options to allow for flexibility in configuration; see the options section for details.

Usage

Add the action to a GitHub Action Workflow file.

A minimal example of a workflow step is below:

    - name: Set Assignee and Reviewer when Checks Ready
      uses: ChrisCarini/set-assignee-reviewer-when-ready@latest
      with:
        assignees: 'ChrisCarini'
        reviewers: 'ChrisCarini'
        token: ${{ secrets.REPO_SCOPE_GITHUB_TOKEN }}

🔧 Installation

  1. Create a .yml (or .yaml) file in your GitHub repository's .github/workflows folder. We will call this file set-assignee-reviewer-when-pr-checks-ready.yml below.
  2. Copy the below contents into set-assignee-reviewer-when-pr-checks-ready.yml 
    name: 'Set Assignee Reviewer on PR when Checks Ready'
on:
 workflow_run:
   workflows:
     - <ENTER_YOUR_WORKFLOW_NAMES_HERE>
   types:
     - completed

jobs:
  set_assignee_reviewers:
    name: "Set Assignee and Reviewer when Checks Ready"
    runs-on: ubuntu-latest
    steps:
      - name: Set Assignee and Reviewer when Checks Ready
        uses: ChrisCarini/set-assignee-reviewer-when-ready@latest
        with:
          assignees: 'ChrisCarini'
          reviewers: 'ChrisCarini'
          delayBeforeRequestingReviews: 30
          token: ${{ secrets.REPO_SCOPE_GITHUB_TOKEN }}

⚙️ Options

This GitHub Action exposes several input options.

Option Table

Input Description Usage Default
token The GitHub token to use for making API requests. Required N/A
acceptableConclusions The acceptable conclusion for each check run that has completed. Defaults to success, neutral, cancelled, skipped. Optional success, neutral, cancelled, skipped
unacceptableConclusions The unacceptable conclusion for each check run that has completed. Defaults to failure, timed_out, action_required. Optional failure, timed_out, action_required
assignees List of assignees to assign the PR to. Defaults to 'no one'. Required (*) No One
reviewers List of reviewers to request reviews on the PR. Defaults to 'no one'. Required (*) No One
requiredChecksOnly Only consider required checks. Defaults to true. Optional true
delayBeforeRequestingReviews If all checks having acceptable conclusions, wait N seconds before requesting reviewers on the PR. Defaults to 0 which disables requesting reviewers on PRs with acceptable checks. Optional 0 (disabled)

(*) = You can set one (ie, either assignees or reviewers), or both of these inputs. Setting neither of these inputs doesn't do anything.

Example using all options

An example using all the available options is below:

    - name: Set Assignee and Reviewer when Checks Ready
      uses: ChrisCarini/set-assignee-reviewer-when-ready@latest
      with:
        acceptableConclusions: 'success'    # The only 'acceptable conclusion' to a check run is `success`.
        unacceptableConclusions: 'failure'  # The only 'unacceptable conclusion' to a check run is `failure`. 
        assignees: 'ChrisCarini'            # Assign the PR to `ChrisCarini`
        reviewers: 'ChrisCarini, scalvert'  # Add `ChrisCarini` & `scalvert` as reviewers of the PR
        requiredChecksOnly: 'false'         # This will cause *all* checks on a PR to need to be 'acceptable' for assignment & requesting review to work.
        delayBeforeRequestingReviews: '300'                  # Wait 5 minutes after all acceptable check runs have completed before assigning / requesting reviews.
        token: ${{ secrets.REPO_SCOPE_GITHUB_TOKEN }}

token

A GitHub token is required for this action in order to make various API calls.

By default, this GitHub action requires a Personal Access Token (PAT) with the repo scope. This is because the API call to get "Status Checks Protection" requires the repo scope in order to function properly.

If you want to set the requiredChecksOnly option to false, you can use the automatically created GITHUB_TOKEN provided by GitHub Actions Workflows.

acceptableConclusions

This optional input allows the user to specify the check run 'conclusions' they want to indicate as 'acceptable'. See the Conclusions section below.

Default Values: 'success, neutral, cancelled, skipped'

To be 'acceptable' means that the PR will NOT be assigned / review requested, UNLESS the delayBeforeRequestingReviews option is also configured.

unacceptableConclusions

This optional input allows the user to specify the check run 'conclusions' they want to indicate as 'unacceptable'. See the Conclusions section below.

Default Values: 'failure, timed_out, action_required'

To be 'unacceptable' means that the PR will immediately be assigned / review requested.

assignees

This 'optional' input allows the user to set the GitHub username(s) to assign a PR. If multiple usernames are desired, separate them by commas (eg. user1, user2, user3).

Note: This is 'optional', but if you set neither assignees nor reviewers, this action does not do anything.

reviewers

This 'optional' input allows the user to set the GitHub username(s) to request reviews from on the PR. If multiple usernames are desired, separate them by commas (eg. user1, user2, user3).

Note: This is 'optional', but if you set neither assignees nor reviewers, this action does not do anything.

requiredChecksOnly

This optional input allows the user to mark if they want all checks, or only required checks on a PR to have an 'acceptable conclusion'.

Setting Default? Description
true ✅ Only required checks on a PR to complete and have an 'acceptable conclusion'
false ❌ ALL checks on a PR to complete and have an 'acceptable conclusion'

delayBeforeRequestingReviews

This optional input allows the user to both:

  1. Specify they want the PR assigned / review requested even if all check runs have 'acceptable conclusions'.
  2. Specify how long to wait, in seconds, before the PR is assigned / review requested.

That is to say, that if this option is set, any check runs with 'acceptable conclusions' will have assignees/reviewers set as configured.

The second item ("how long to wait") is intended provide 'buffer time', allowing any bots / workflows / apps that are configured to auto-merge PRs once all checks have completed.

If you want any check runs with 'acceptable conclusions' to have assignees/reviewers set as configured right away, set this value to something small (ie, 1).

If you want to disable this functionality entirely, leave the value as the default of 0, or manually specify in your workflow for explicitness.

Conclusions

GitHub Actions can have several different 'conclusions' for each check run once they are complete.

Below are the 'conclusions':

  • action_required
  • cancelled
  • failure
  • neutral
  • skipped
  • success
  • timed_out

For the most up-to-date list, search 'conclusion' on the GitHub REST API Docs page for 'Checks / Check Runs'.

Examples

As examples of using this plugin you can check out following projects:

  • TODO

🤝 Contributing

Contributions welcomed! Feel free to open a PR, or issue.

See CONTRIBUTING.md for more details.

👷 🚧 Developer Notes 🚧 👷

Developer Quick Start

⚠️ NOTE: This section is intended for developers in this repository.

Install dependencies

npm install

Build the typescript source & package for distribution

npm run build && npm run package

Run tests

npm test

Manual Integration Testing Notes

When authoring this GitHub Action, I performed the below tests manually. Why manually? Because I had to manually configure the repo branch protection rules to require different types of checks. This could possibly be automated some day, but not today.

  • ✅ 2022-09-10 - passed: both required checks (both expected to succeed) in single workflow file
  • ✅ 2022-09-10 - passed: both required checks (one expected to succeed; the other fail) in split workflow files
  • ✅ 2022-09-10 - passed: both required checks (one expected to succeed; the other fail) in single workflow file
  • ✅ 2022-09-10 - passed: both required checks (both expected to succeed) in split workflow files

Debugging

This action has GitHub Actions Debug Logging.

To enable, set the following secret in the repository that contains the workflow using this action to true.

  • ACTIONS_STEP_DEBUG

You can find this under the repositories Settings -> Secrets menu.