🐶 Patchron

GitHub bot 🤖 that performs initial pull request code review. It is intended to faster further code reviews, not substitute human ones 😎

• versioned rules
• built with Probot
• easy to configure and expand
• includes tests (Jest) and type definitions (jsdoc)
• wrapped with own context to improve logging and accessing Probot's context

Disclaimer

review is based upon patches (to not overload GitHub API) which contain limited number of information. Due to that, some comments might be unrelevant. Despite of that, it comes to clicking resolve button while at the same time reviewers don't have to focus on simple things.

1. Setup

with Node.js

1. Clone repository.

2. Install dependencies.

   npm install

3. Run the bot.

   npm start

4. Follow further instructions from terminal to finish setup.

with Docker

1. Pull image from GHCR or build your own.

   docker pull ghcr.io/trolit/patchron:latest

   docker build -t patchron .

2. Obtain APP_ID and PRIVATE_KEY.

   Install app via marketplace https://github.com/apps/patchron and configure repository access. Afterwards visit app https://github.com/settings/installations, note down APP_ID and generate PRIVATE_KEY.

3. Create running container from image (APP_ID and PRIVATE_KEY are mandatory)

   docker run -e APP_ID=<app-id> -e PRIVATE_KEY=<pem-value> patchron
   
   more options:
   -e SENDERS=<usernames-separated-by-comma>
   -e MAX_COMMENTS_PER_REVIEW=<number>

with GitHub Actions

Use GitHub Token or PAT

You can use GitHub token that is generated automatically on event (comments will be associated with github-actions bot) or personal access token to associate review with e.g. your own bot account. In that case you only need to add following snippet to repository workflow and adjust it to your needs.

name: Perform first PR review (GITHUB TOKEN)

on:
    pull_request:
        types:
            - opened

jobs:
    reviewOpenedPull:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v3
            with:
                repository: 'trolit/Patchron'
                ref: 'master'

            - run: npm ci --only=production

            - run: npm start
            # options: https://github.com/trolit/Patchron#2-configuration
            env:
                GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # or secrets.PAT
                # when 'github' is assigned, attempts to read variables directly from workflow
                NODE_ENV: 'github'

Use app installation token

⚠️ Note: Snippet uses @navikt/github-app-token-generator to generate app installation token. You can provide different solution (or your own). At this moment probot/adapter-github-actions does not support to generate app installation token by app id and private key.

1. Install app via marketplace https://github.com/apps/patchron

2. Configure repository access (repository that you want to be reviewed should be accessible by app).

3. Generate PRIVATE_KEY

4. Add APP_ID and PRIVATE_KEY secrets to repository

5. Use following snippet to add workflow in your repository.

   name: Perform first PR review (APP INSTALLATION TOKEN)
   
   on:
       pull_request:
           types:
               - opened
   
   jobs:
       reviewOpenedPull:
           runs-on: ubuntu-latest
           steps:
               - uses: navikt/github-app-token-generator@v1
               id: get-token
               with:
                   private-key: ${{ secrets.PRIVATE_KEY }}
                   app-id: ${{ secrets.APP_ID }}
   
               - uses: actions/checkout@v3
               with:
                   repository: 'trolit/Patchron'
                   ref: 'master'
   
               - run: npm ci --only=production
   
               - run: npm start
               # options: https://github.com/trolit/Patchron#2-configuration
               env:
                   GITHUB_TOKEN: ${{ steps.get-token.outputs.token }}
                   # when 'github' is assigned, attempts to read variables directly from workflow
                   NODE_ENV: 'github'

Rules configuration examples 🧩

• Default (rules categorised by file extension)
• Node (commonjs) + Vue in single repository (rules split by relative path and file extension)

How to arrange own rules 🤔

Rules config file is expected to be expressed as .json with specific structure to unify app behaviour between all available ways of serving it. It should have pull array and files object. Pull rules are intended to verify pull request data (not changes in files) and that's why it has separated section. You can manage configuration in two ways:

via extension

{
    "pull": [],
    "files": {
        "js": [],
        "vue": [],
        "cs": []
    }
}

It's used in repository as default configuration here. When app fetches files from pull request event, it takes each filename and attempts to get related rules from files object by file extension. If e.g. bot receives src/helpers/doSomething.js it will attempt to get rules from rules.files['js'].

via relative paths

There might be a case where single repository is used to store more app parts (e.g. client and server) and you would like to separate client rules from server (because for example server is in commonjs type and client in module). To solve it, you can group rules by relative paths:

{
    "pull": [],
    "files": [
        "server/*": {
            "js": [
                { }
            ]
        },
        "client/*": {
            "js": [
                { }
            ],
            "vue": [
                { }
            ]
        }
    ]
}

⚠️ End relative paths with asterisks (e.g. server/*) if you want to match files that are stored under server/ regardless of the nesting level.

• server/*

  • server/doSomething.js (matched)
  • server/helpers/chart/saveLegendItems.js (matched)

• server

  • server/doSomething.js (matched)
  • server/helpers/chart/saveLegendItems.js (not matched)

2. Configuration

Property	Type (default)	Description
NODE_ENV	String ( )	specifies environment in which app is running. For GitHub actions use github, for testing purposes test and for self hosted app production. GitHub POST comments, summary, approve actions are limited to github and production environments.
RULES_CONFIGURATION_PATH	String (src/config/rules)	Path to rules configuration file stored in project. Used when RULES_CONFIGURATION_URL is not provided.
RULES_CONFIGURATION_URL	String ( )	When provided, attempts to fetch rules configuration from given URL. URL should point to .json file (example structure).
IS_GET_FILES_REQUEST_PAGINATED	boolean (false)	Controls files fetching strategy. Unpaginated response includes a maximum of 3000 files which is sufficient in 99.9999999999% of cases.
DELAY_BETWEEN_COMMENT_REQUESTS_IN_SECONDS	Number (3)	After pull request review is done, delays time between each comment POST request to not overload GitHub API. Creating content too quickly may result in secondary rate limiting.
IS_OWNER_ASSIGNING_ENABLED	boolean (true)	When true, PR owner will be automatically assigned on issueing pull request.
IS_REVIEW_SUMMARY_ENABLED	boolean (false)	When true, at the end of the PR review, app will post summary that contains various information e.g. total comments that were successfully posted.
IS_STORING_LOGS_ENABLED	boolean (false)	When true, logs are also stored physically in .logs directory. Log files are named in following format: YYYY-MM-DD.
MAX_COMMENTS_PER_REVIEW	Number (25)	Limits number of comments that can be posted in single review under single pull request.
SENDERS	String ( )	Allows to limit pull requests reviews to certain users. Pass string with usernames separated by comma e.g. 'test1, test2, test3'
APPROVE_PULL_ON_EMPTY_REVIEW_COMMENTS	boolean (true)	When true, approves pull request on empty review comments.

3. Useful links

• Probot docs
• Octokit Rest API
• Deployments API example
• Pino (logger)
• GitHub API - best practices
• GitHub API - rate limits
• GitHub API - pulls
• Default picture

4. Name origin

Name simply comes from merging two words: Patch and Patron 🐶