Description

This pull request refactors how pull request reviewer updates are handled, switching from the GraphQL API to the REST API for adding and removing reviewers. It also improves the logic for managing reviewer lists, especially in non-interactive and interactive editing modes, and updates the test suite to cover these changes and edge cases.

Also fixes a bug where the PR author was included in the interactive list of reviewers. With GraphQL this selection would be ignored, but the REST API actually returns an error if the PR author is provided, so we need to fix that now to avoid confusion.

fixes #4844

Considerations

Moving to the REST API with this allows us to add/remove as separate operations, eliminating the need to fetch org teams and org team IDs. This is good, because it allows the GITHUB_TOKEN and other repo scoped authentication types to proceed with requesting a user review.

However, there's a drawback that we now will require two operations, one for adding reviewers and one for removing.

I am fine with this trade-off because I suspect the typical use-case will only involve either requesting a reviewer or removing a reviewer as discrete operations. Meaning, in most cases we'll never actually perform two API calls. Nonetheless the risk is there.

This implementation also proposes that these two API requests be performed concurrently. I suspect this is optimal, but I am unsure of any sort of race-condition that could arise. In particular in the case of removing and adding the same reviewer, but that could be seen as user error.

Testing

This was tested in Actions to prove that it will allow requesting a user reviewer without requiring access to teams, meaning the GITHUB_TOKEN could be used where currently gh will fail.

name: Test Team Reviewer

on:
  workflow_dispatch:
    inputs:
      pr_number:
        description: 'PR number to add reviewer to'
        required: true
        type: string

jobs:
  add-individual-reviewer-local-gh:
    runs-on: self-hosted
    continue-on-error: true
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Add individual reviewer using local gh binary (should pass if permissions allow)
        env:
            GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          <LOCAL_GH_PATH>/gh pr edit ${{ github.event.inputs.pr_number }} --add-reviewer "<INDIVIDUAL_REVIEWER_USERNAME>"

  add-team-reviewer-local-gh:
    runs-on: self-hosted
    continue-on-error: true
    needs: add-individual-reviewer-local-gh
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Add team reviewer using local gh binary (may fail if token lacks team review permission)
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          <LOCAL_GH_PATH>/gh pr edit ${{ github.event.inputs.pr_number }} --add-reviewer "<ORG_SLUG>/<TEAM_SLUG>"

  add-team-reviewer-system-gh:
    runs-on: self-hosted
    continue-on-error: true
    needs: add-team-reviewer-local-gh
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Add team reviewer using system gh (may fail if permissions insufficient)
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh pr edit ${{ github.event.inputs.pr_number }} --add-reviewer "<ORG_SLUG>/<TEAM_SLUG>"

  add-individual-reviewer-system-gh:
    runs-on: self-hosted
    continue-on-error: true
    needs: add-team-reviewer-system-gh
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Add individual reviewer using system gh
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh pr edit ${{ github.event.inputs.pr_number }} --add-reviewer "<INDIVIDUAL_REVIEWER_USERNAME>"

You can see the first job is successful, which is what we're going for. We want the GITHUB_TOKEN to be able to request a review from a user as long as there isn't teams included in the review request.

Further Improvements

It should be noted that the REST API doesn't return a satisfying or useful error message when you provide it a team reviewer without having access to org teams, as in the case of the GITHUB_TOKEN:

Perhaps there is further work to be done in the future to improve this error messaging client-side.