GitHub Action
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.
- ✨ 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.
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 thegithub-actions
bot will run the job for you.
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 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.
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. |
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.
- If the issues are linked manually and are not mentioned in the pull request body, the pull request is still considered to be invalid.
Thanks goes to these wonderful people (emoji key):
Cristopher 💻 🐛 📖 💡 🤔 |
Samuel Mutel 🐛 |
This project follows the all-contributors specification. Contributions of any kind are welcome!
This project is licensed under the MIT License