Conventional PR

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:

Pull request status is a draft.
Pull request is submitted by a bot.
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:

Pull request has a valid title.
Pull request has a non-empty body.
Pull request mentioned one or more issue.
Pull request does not introduce too many file changes.
All commits in the pull request have valid messages.
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.
`report`	`false`	`true`	Determines whether pull request report should be written as a pull request comment

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.
Due to GitHub limitations, it is not possible to modify the state of the pull request from a forked repository. To address this issue, you have to set close to false and report to false to prevent the workflow from closing the pull request and creating new comment.