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.9.0

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.9.0
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:
    # You can add specific pull request types too.
    # If this is omitted, the workflow will only executed on opened, synchronize, and reopened
    # which is enough for generic use cases.
    # Below is the list of supported pull request sub-events
    # types: [opened, reopened, ready_for_review, unlocked, synchronize]

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 commit message validation.
branch_pattern false '' Valid pull request branch name regex pattern in Perl syntax. Fill with an empty string to disabled branch name 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.
verified_commits false false Require all commits on the pull request to be signed commits
ignored_users false '' GitHub usernames to be whitelisted from pull request validation. Must be a comma-separated string. Example: Namchee, foo, bar will bypass pull request validation for users Namchee, foo, bar. Case-sensitive.

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.
sychronize When a pull request has changes on its history, such as pushing new commits to the branch.
unlocked When a pull request is unlocked.

Omitting types is enough for generic use-cases since omitting it will cause the workflow to be triggered on opened, reopened, and synchronize events.

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
🐛
Noah Sherwin
🐛 🤔

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

License

This project is licensed under the MIT License