Extremely powerful GitHub Action to streamline management of PRs through automation of common tasks. Very versatile with plenty of configuration settings to adapt to many different implementations.

Currently supports the following functionality:

• Welcome message on new PR
• Automatic Label assignment and removal
  • Based on Review criteria (required/provided)
  • If PRs qualify for automatic merge
• PR Comment automation
  • Welcome message with instructions on new PRs
  • Assign a label indicating if the PR is ready or on hold based on key words
• Pull Request Reviewers
  • Automatically assign reviewers from YAML front matter
  • Name matching to github username via Jekyll or DocFX Author/People YAML file. More details here.
• Pull Request Merge
  • Automatically merge when criteria is met
  • Respect requested reviews (i.e. CODEOWNERS)
  • Respect a minimal review count (for now configured by input param, repo setting on roadmap)
  • Delete branch (head ref) on merge

The Action can respond to the following workflow events:

• pull_request
• pull_request_review
• issue_comment
• schedule

Set the following inputs in the workflow file

Required The token to use for github authentication. Recommend using ${{ secrets.GITHUB_TOKEN }}. If additional access is required use a PAT/Secret and set it as a secret. More info see here.

If you have enabled Branch Protection rules then a PAT/Secret will need to be configured.

Required Set to true to enable the auto merge capabilities

Required Set to true to enable the PR/Issue comment automation

Required Set to true to enable the PR label automation

Set to true to enable reviewers to be set from owner in YAML front matter.

Required Set to true to automatically send a welcome message to new contributors

The custom welcome message to send to new contributors

Requires enable-welcomemessage: true

Set to true if all checks need to complete before auto merging

Should match the setting in your GitHub repo. Set it to -1 to disable.

The method to use when merging the PRs

Set to true to require a path check for auto merge capabilities

Requires enable-prmerge-automation: true

Provide the path globs which will allow auto merge. JSON object as string, example format {"any":["docs/**"]}.

Requires prmerge-pathcheck: true

If true then the branch will be deleted on merge

Requires enable-prmerge-automation: true

Provide the branch patterns which will allow/deny auto delete on merge. JSON object as string, example format {"deny":["dev"]}.

Requires prmerge-deletebranch: true

The key in the YAML front matter to define the article author(s), who will be assigned as reviewers. Defaults to author

---
title: My great article
author: octocat
---

Requires enable-prreviewer-frontmatter: true

When set to true enables the lookup of the author from the Jekyll style Author YAML file

Requires enable-prreviewer-frontmatter: true

Provides the ability to configure the path to the Jekyll authors YAML file to use in lookup. Default is docs/_data/authors.yml

Requires enable-prreviewer-frontmatter: true and prreviewer-githubuserfromauthorfile: true

Provides the ability to by pass review checks when all the changed files are owned by the author of the PR. If you configure Branch Protection within GitHub security, then it may block this setting from working. Configuring the prmerge-requirereviewcount setting in it's place will not affect this setting.

Requires enable-prreviewer-frontmatter: true

The initial label to set on PRs when first created

The label to use when the PR has been signed off and ready for merge

The label to use when the PR is on hold

The label to use when the PR requires reviews

The label to set on PRs when it qualifies for automatic merge by this action

None

Create the following file within your repo as .github/workflows/pullrequest.yml to configure an action.

name: PR Helper

on: [pull_request, pull_request_review, issue_comment]

jobs:
  prhelper_job:
    runs-on: ubuntu-latest
    steps:
    - name: Run PR Helper
      id: runprhelper
      uses: Matticusau/pr-helper@v1.2.4
      with:
        repo-token: ${{ secrets.GITHUB_TOKEN }}

Note: The uses syntax includes tag/branch specification. For the latest release see tags.

To restrict the branches that this workflow executes on use this syntax

name: PR Helper

on:
  pull_request:
    branches:
      - master
  pull_request_review:
    branches:
      - master
  issue_comment:
    branches:
      - master
jobs:
  ...

The action can be customized using the additional inputs on the workflow yaml file. This will always be read from the default branch of the repository, rather than custom yaml config files which can be overridden as they are read in the branch where the workflow is triggered from.

with:
  repo-token: ${{ secrets.GITHUB_TOKEN }}
  enable-prmerge-automation: true
  enable-prcomment-automation: true
  enable-prlabel-automation: true
  enable-prreviewer-frontmatter: false
  enable-welcomemessage: true
  welcome-message: "Thanks for opening an issue! Make sure you've followed CONTRIBUTING.md."
  prmerge-requireallchecks: true
  prmerge-requirereviewcount: 1
  prmerge-method: 'merge'
  prlabel-default: 'pr-onhold'
  prlabel-ready: 'pr-ready'
  prlabel-onhold: 'pr-onhold'
  prlabel-reviewrequired: 'review-required'
  prlabel-automerge: 'auto-merge'

Labels will be created during the assignment if they do not exist. The following are suggested labels and colors:

If you are having issues running the action enable the debug logs as some additional logging has been built into the Action.

1. To enable runner diagnostic logging, set the following secret in the repository that contains the workflow: ACTIONS_RUNNER_DEBUG to true.
2. To download runner diagnostic logs, download the log archive of the workflow run. The runner diagnostic logs are contained in the runner-diagnostic-logs folder. For more information on downloading logs, see Downloading logs.

Enable debug logging

From https://docs.github.com/en/actions/reference/events-that-trigger-workflows#pull-request-events-for-forked-repositories

Note: Workflows do not run on private base repositories when you open a pull request from a forked repository.

To work around this use the schedule event. This action supports the schedule event for Label, Review, and Merge features. Currently the Welcome message functionality is only supported for pull_request events.

Example YAML for running the action every day at 1am.

name: PR Merge on Schedule

on:
  schedule:
    - cron: '* 1 * * *'

jobs:
  prhelper_schedule:
    runs-on: ubuntu-latest
    steps:
    - name: Run PR Helper on Schedule
      id: runprhelperonschedule
      uses: Matticusau/pr-helper@v1.2.4
      with:
        repo-token: ${{ secrets.GHACTION_PAT }}
        enable-prmerge-automation: true
        enable-prcomment-automation: false
        enable-prlabel-automation: true
        enable-prreviewer-frontmatter: true
        enable-welcomemessage: false
        prmerge-requireallchecks: true
        prmerge-requirereviewcount: 1
        prmerge-method: 'merge'
        prmerge-deletebranch: 'true'
        prmerge-deletebranch-config: ''
        prmerge-pathcheck: true
        prmerge-allowpaths: '{"any":["articles/**"]}'
        prreviewer-authorkey: 'author'
        prreviewer-githubuserfromauthorfile: true
        prreviewer-authorfilepath: '_data/authors.yaml'
        prlabel-default: 'pr-onhold'
        prlabel-ready: 'pr-ready'
        prlabel-onhold: 'pr-onhold'
        prlabel-reviewrequired: 'review-required'
        prlabel-automerge: 'auto-merge'

When using the CODEOWNERS feature and multiple files with different CODEOWNERS are modified. Even though you meet the minimum number of reviewers if there is still pending reviews from CODEOWNERS for files with no review yet, then this will block the merge and may throw an error on the action workflow.