This action checks if PR titles conform to the Contribution Guidelines ☑️
Consistent title names help maintainers organise their projects better 📚
Shows if the author has reaaaaally read the Contribution Guidelines :P
Create a config file .github/pr-title-checker-config.json
like this one below:
{
"LABEL": {
"name": "title needs formatting",
"color": "EEEEEE"
},
"CHECKS": {
"prefixes": ["fix: ", "feat: "],
"regexp": "docs\\(v[0-9]\\): ",
"regexpFlags": "i",
"ignoreLabels" : ["dont-check-PRs-with-this-label", "meta"]
},
"MESSAGES": {
"success": "All OK",
"failure": "Failing CI test",
"notice": ""
}
}
You can pass in one of prefixes
or regexp
or even both based on your use case. regexpFlags
and ignoreLables
are optional fields.
If LABEL.name
is set to ""
, adding or removing labels will be skipped. The CI test will continue to pass/fail accordingly.
If none of the checks pass, a label will be added to that pull request.
If at least one of them passes, the label will be removed.
This action causes CI tests to fail by default. However, if you do not want CI tests failing just because of this action, simply set alwaysPassCI
as true in the CHECKS field. An invalid config file will always cause the action to fail.
Adding label names to the optional ignoreLabels
field will forfeit any checks for PRs with those labels.
The config file is always pulled from the action's context, i.e., the branch from which the pull request is made.
See other ways to specify config file.
Action returns a single output: success
that indicates if check has passed or failed.
Create a workflow file (eg: .github/workflows/pr-title-checker.yml
) with the following content:
name: "PR Title Checker"
on:
pull_request_target:
types:
- opened
- edited
- synchronize
- labeled
- unlabeled
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: thehanimo/[email protected]
with:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
pass_on_octokit_error: false
configuration_path: .github/pr-title-checker-config.json #(optional. defaults to .github/pr-title-checker-config.json)
To learn more about workflows, see Create an example workflow.
...
steps:
- uses: thehanimo/[email protected]
with:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
pass_on_octokit_error: false
remote_configuration_path: "https://raw.githubusercontent.com/grpc/grpc/master/.github/pr_title_checker_config.json"
...
Note that this has to be a url pointing to a valid, raw json file. See #28
...
steps:
- uses: thehanimo/[email protected]
with:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
pass_on_octokit_error: false
github_configuration_owner: RocketChat #(optional. defaults to the owner of the repo in which the action is run)
github_configuration_repo: Rocket.Chat #(optional. defaults to the repo in which the action is run)
github_configuration_path: .github/pr-title-checker-config.json #(optional. defaults to .github/pr-title-checker-config.json)
github_configuration_ref: <named branch, tag, or SHA> #(optional. defaults to the latest commit on the default branch or, if the repo specified is the same as the one on which the action is running, it defaults to the current context's sha)
github_configuration_token: ${{ secrets.YOUR_TOKEN }} #(optional. defaults to GITHUB_TOKEN)
...
...
steps:
- uses: thehanimo/[email protected]
with:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
pass_on_octokit_error: false
local_configuration_path: .github/actions/enforce-pr-titles/config.json
...
This is useful if a repo containing the config file is pulled in a previous step using, for e.g., actions/checkout. See #36
You can use the action output to execute follow up steps e.g. adding a comment.
steps:
- uses: thehanimo/[email protected]
id: check
continue-on-error: true
with:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
pass_on_octokit_error: false
- name: Add comment to fix PR title
uses: marocchino/sticky-pull-request-comment@v2
if: ${{ steps.check.outputs.success == 'false'}}
with:
header: 'PR Title Check'
recreate: true
message: |
### 🚨 PR Title Needs Formatting
The title of this PR needs to be formatted correctly and include an Azure Boards Reference.
Please update the title to match the format `type: description AB#xxx`. Examples:
* `bugfix: fix typo in README.md AB#123`
* `chore: update dependencies AB#456`
* `feat: add new feature AB#789`
* `chore: fixing build pipeline` - no AB reference
- name: Add comment that PR title is fixed
if: ${{ steps.check.outputs.success == 'true'}}
uses: marocchino/sticky-pull-request-comment@v2
with:
header: 'PR Title Check'
recreate: true
message: |
### ✅ PR Title Formatted Correctly
The title of this PR has been updated to match the correct format. Thank you!
pull_request_target
event trigger should be used (notpull_request
) in order to support checking PRs from forks. This was added inv1.3.2
. See #8.pass_on_octokit_error
is an optional input which defaults to false. Setting it to true will prevent the CI from failing when an octokit error occurs. This is useful when the environment this action is run in is not consistent. For e.g, it could be a missing GITHUB_TOKEN. Thanks to @bennycode for pointing this out.