Skip to content
You're viewing an older version of this GitHub Action. Do you want to see the latest version instead?
compass

GitHub Action

Conventional PR

v0.7.1

Conventional PR

compass

Conventional PR

Validates and enforces clean pull request style in your GitHub projects without hassle

Installation

Copy and paste the following snippet into your .yml file.

 
              
- name: Conventional PR

              
  uses: Namchee/conventional-pr@v0.7.1
Learn more about this action in Namchee/conventional-pr

Choose a version

Conventional PR

Go Version Badge Go Report Card codecov All Contributors

Conventional PR is a GitHub Action that validates all pull requests sent to a GitHub-hosted repository.

Conventional PR aims to ease your burden in managing your GitHub-hosted repository by validating, marking, even moderating low-quality attempts of pull request just by integrating Conventional PR to your existing CI/CD workflow.

Features

  • ✨ Configurable, tune Conventional PR easily to suit your needs.
  • 💡 Sensible defaults, validates pull request with out-of-the-box sensibility.
  • ♿ Whitelisting, validates pull request that actually matters.
  • 📈 Transparent reporting, see what Conventional PR is actually doing.

Usage

To use Conventional PR, you'll need to prepare a GitHub access token. Please refer to this article on how to generate an access token.

You can integrate Conventional PR to your existing CI/CD workflow by using Namchee/conventional-pr@<version> in one of your jobs using the YAML syntax.

Below is the example of creating a new Conventional PR workflow in your CI/CD workflow.

on:
  pull_request: # Required to only listen to pull request events, else it will always fail
    types: [opened, reopened, ready_for_review] # Recommended

jobs:
  cpr:
    runs-on: ubuntu-latest
    steps:
      - name: Validates the pull request
        uses: Namchee/conventional-pr@v(version)
        with:
          access_token: YOUR_GITHUB_ACCESS_TOKEN_HERE

Please refer to GitHub workflow syntax for more advanced usage.

Access token is required. Please generate one or use ${{ secrets.GITHUB_TOKEN }} as your access token and the github-actions bot will run the job for you.

Whitelist

Whitelist is one of the features of Conventional PR that allows you to bypass pull request validaton if the pull request satisfies one or more enabled whitelisting criteria.

Currently, there are 3 whitelisting criteria that are available in Conventional PR:

  1. Pull request status is a draft.
  2. Pull request is submitted by a bot.
  3. Pull request is submitted by a user with high administrative privileges.

All whitelists are configurable. Please refer to the inputs section on how to configure whitelists.

Validator

Validator is the core feature of Conventional PR. Validator will validate pull request that triggers the workflow according to a specified criteria.

A pull request is considered to be valid if it satisfies all enabled validation flow.

Currently, there are 6 validation flow that are available in Conventional PR:

  1. Pull request has a valid title.
  2. Pull request has a non-empty body.
  3. Pull request mentioned one or more issue.
  4. Pull request does not introduce too many file changes.
  5. All commits in the pull request have valid messages.
  6. Pull request has a valid branch name.

All validators are configurable. Please refer to the inputs section on how to configure whitelists.

Inputs

You can customize this actions with these following options (fill it on with section):

Name Required? Default Value Description
access_token true GitHub access token to interact with the GitHub API. It is recommended to store this token with GitHub Secrets.
close false true Determine whether conventional pr should attempt to automatically close invalid pull requests.
template false `` Comment template to use when commenting on invalid pull requests. Fill with an empty string to disable further comments.
label false conventional pr:invalid Label to use when marking invalid pull requests. If it doesn't exist, this action will automatically create it. Fill with an empty string to disable labeling.
draft false true Determine whether conventional pr should skip validating draft pull requests.
strict false true Determine whether the restrictions should apply to repository administrators.
bot false true Determines whether checks should be skipped on PRs that is created by bots. Useful when relying on bots like dependabot
title_pattern false ([\w\-]+)(\([\w\-]+\))?!?: [\w\s:\-]+ Valid pull request title regex pattern in Perl syntax. Defaults to the conventional commit style commit messages. Fill with an empty string to disabled pull request title validation.
commit_pattern false `` Valid pull request commit messages regex pattern in Perl syntax. Fill with an empty string to disabled pull request title validation.
branch_pattern false `` Valid pull request branch name regex pattern in Perl syntax. Fill with an empty string to disabled pull request title validation.
body false true Determine whether a valid pull request should always have a non-empty body.
issue false true Determine whether a valid pull request should always have an issue or pull requests references on it.
maximum_file_change false 0 Limits how many file can be changed per one pull request. Fill with zero to disable this feature.

Supported Events

Ideally, Conventional PR workflow should only triggered when an event related to pull requests is fired. However, Conventional PR is only able to function properly with some pull request sub-events and will ignore the rest. Below is the list of supported GitHub Action pull request sub-events:

Name Triggered On
opened When a new pull request is submitted.
reopened When a closed pull request is re-opened, either by the original author or by someone else.
ready_for_review When a draft pull request is finished and transformed into normal pull request.

It is recommeneded to only listen to pull_request sub-events as listening to incorrect event may cause the workflow to fail.

Caveats

  • If the issues are linked manually and are not mentioned in the pull request body, the pull request is still considered to be invalid.

Contributors ✨

Thanks goes to these wonderful people (emoji key):


Cristopher
💻 🐛 📖 💡 🤔
Samuel Mutel
🐛

This project follows the all-contributors specification. Contributions of any kind are welcome!

License

This project is licensed under the MIT License