Advanced Commit Linter is a GitHub Action that lint commit messages of PR. It checks for issue trackers and upstream references. Results can be displayed as a status check or Pull Request comment when used together with issue-commentator GitHub Action.
TBA
- Tracker references validator
- Upstream references (cherry-pick) validator
To set up Advanced Commit Linter, we need three files:
- Workflow that captures Pull Request metadata (number and commit metadata) and uploads this data as an artifact
- Workflow that runs on
workflow-runtrigger, downloads artifact, and runsadvanced-commit-linterGitHub Action advanced-commit-linter.ymlconfiguration
Note: Setup is complicated due to GitHub permissions on
GITHUB_TOKEN. When used in workflow executed from fork it hasread-onlypermissions. By using theworkflow-runtrigger we are able to safely overcome this limitation and it allows us to comment on Pull Requests.
policy:
cherry-pick:
upstream:
- github: systemd/systemd
- github: systemd/systemd-stable
exception:
note:
- rhel-only
tracker:
- keyword:
- 'Resolves: #'
- 'Related: #'
type: bugzilla
issue-format:
- '[0-9]+$'
url: 'https://bugzilla.redhat.com/show_bug.cgi?id='
exception:
note:
- github-only
- keyword:
- 'Resolves: '
- 'Related: '
type: jira
issue-format:
- 'JIRA-1234'
url: 'https://issues.redhat.com/browse/'
exception:
note:
- github-onlyname: Gather Pull Request Metadata
on:
pull_request:
types: [ opened, reopened, synchronize ]
branches: [ main ]
permissions:
contents: read
jobs:
gather-metadata:
runs-on: ubuntu-latest
steps:
- name: Repository checkout
uses: actions/checkout@v3
- id: Metadata
name: Gather Pull Request Metadata
uses: redhat-plumbers-in-action/gather-pull-request-metadata@v1
- name: Upload artifact with gathered metadata
uses: actions/upload-artifact@v3
with:
name: pr-metadata
path: ${{ steps.Metadata.outputs.metadata-file }}name: Commit Linter
on:
workflow_run:
workflows: [ Gather Pull Request Metadata ]
types:
- completed
permissions:
contents: read
jobs:
download-metadata:
if: >
github.event.workflow_run.event == 'pull_request' &&
github.event.workflow_run.conclusion == 'success'
runs-on: ubuntu-latest
outputs:
pr-metadata: ${{ steps.Artifact.outputs.pr-metadata-json }}
steps:
- id: Artifact
name: Download Artifact
uses: redhat-plumbers-in-action/download-artifact@v1
with:
name: pr-metadata
commit-linter:
needs: [ download-metadata ]
runs-on: ubuntu-latest
outputs:
validated-pr-metadata: ${{ steps.commit-linter.outputs.validated-pr-metadata }}
permissions:
# required for creation of checks
checks: write
steps:
- id: commit-linter
name: Lint Commits
uses: redhat-plumbers-in-action/advanced-commit-linter@v1
with:
pr-metadata: ${{ needs.download-metadata.outputs.pr-metadata }}
token: ${{ secrets.GITHUB_TOKEN }}Action currently accepts the following options:
# ...
- uses: redhat-plumbers-in-action/advanced-commit-linter@v1
with:
pr-metadata: <pr-metadata.json>
config-path: <path to config file>
set-status: <true or false>
status-title: <h3 title of status message>
token: <GitHub token or PAT>
# ...Stringified JSON Pull Request metadata provided by GitHub Action redhat-plumbers-in-action/gather-pull-request-metadata.
Pull Request metadata has the following format: metadata format
- default value:
undefined - requirements:
required
Path to configuration file. Configuration file format is described in: Policy section.
- default value:
.github/advanced-commit-linter.yml - requirements:
optional
Set status on Pull Request. If enabled, Action will create check-run with validation results.
- default value:
false - requirements:
optional
Optional H3 title of status message.
- default value:
Commit validation - requirements:
optional
GitHub token or PAT is used for setting status checks on Pull Request.
# required permission
permissions:
checks: write
pull-requests: write- default value:
undefined - requirements:
required - recomended value:
secrets.GITHUB_TOKEN
Action is configured using special policy file: .github/advanced-commit-linter.yml. The structure needs to be as follows:
policy:
cherry-pick:
upstream:
- github: systemd/systemd
- github: systemd/systemd-stable
exception:
note:
- rhel-only
tracker:
- keyword:
- 'Resolves: #'
- 'Related: #'
type: bugzilla
issue-format:
- '[0-9]+$'
url: 'https://bugzilla.redhat.com/show_bug.cgi?id='
exception:
note:
- github-only
- keyword:
- 'Resolves: '
- 'Related: '
type: jira
issue-format:
- 'RHELPLAN-\d+$'
url: 'https://issues.redhat.com/browse/'
exception:
note:
- github-onlyThe section that specifies upstreams for which you frequently cherry-pick.
- requirements:
optional
An array of upstreams. Currently, the only supported upstream location is GitHub.
Supported keys:
github- GitHub repository in format<org>/<repo>- requirements:
required
Property that describes possible exceptions for referencing upstream commits in commit messages. Currently supported exceptions:
note- for exampledownstream-onlyorrhel-only
The section specifies the form and type of required trackers.
Keyword that prefixes tracker identificator.
- requirements:
required - example:
Fixes:
Type of tracker. Data can be used by postprocessing scripts/GitHub Actions.
Currently supproted types of trackers are: bugzilla, jira and unknown.
- requirements:
required
Regex that describes identificator of given tracker.
- requirements:
required - example:
[0-9]+$
Url to better display detected trackers in Pull Request comment as a link. Tracker ID will be appended at the end of url.
- requirements:
optional - example:
https://issues.redhat.com/browse/
Property that describes possible exceptions for referencing trackers in commit messages. Currently supported exceptions:
note- for examplegithub-onlyortests-only
Example of validated metadata object
const metadata = {
number: 15,
labels: [
{
id: 5610751380,
name: 'bug',
description: 'Bug label',
},
],
milestone: {},
commits: [
{
sha: 'b145cbd729d33cc50d299079a9a5c643531ad053',
url: 'https://github.com/redhat-plumbers-in-action/advanced-commit-linter/commit/b145cbd729d33cc50d299079a9a5c643531ad053',
message: {
title: 'fix Typo in README.md',
body: 'fix: typo\
\
rhel-only\
\
Related: RHELPLAN-1234',
cherryPick: [],
},
validation: {
status: 'success',
message:
'| https://github.com/redhat-plumbers-in-action/advanced-commit-linter/commit/b145cbd729d33cc50d299079a9a5c643531ad053 - _fix: typo_ | `rhel-only` |',
tracker: {
status: 'success',
message:
'[RHELPLAN-1234](https://issues.redhat.com/browse/RHELPLAN-1234)',
data: [
{
data: {
keyword: 'Related: ',
id: 'RHELPLAN-1234',
type: 'jira',
url: 'https://issues.redhat.com/browse/RHELPLAN-1234',
},
},
],
},
upstream: {
data: [],
status: 'success',
exception: 'rhel-only',
},
},
},
],
validation: {
status: 'success',
tracker: {
message: 'Tracker found',
type: 'unknown',
id: 'RHELPLAN-1234',
url: 'https://issues.redhat.com/browse/RHELPLAN-1234',
},
message:
'Tracker - [RHELPLAN-1234](https://issues.redhat.com/browse/RHELPLAN-1234)\
\
#### The following commits meet all requirements\
\
| commit | upstream |\
|---|---|\
| https://github.com/redhat-plumbers-in-action/advanced-commit-linter/commit/b145cbd729d33cc50d299079a9a5c643531ad053 - _fix: typo_ | `rhel-only` |',
},
};Status of commit validation. Can be one of the following values:
success- commit meets all requirementsfailure- commit does not meet all requirements
Message that describes commit validation status.
Object that describes all trackers detected in commit message and their validation status.
tracker: {
status: 'success',
message: '[RHELPLAN-1234](https://issues.redhat.com/browse/RHELPLAN-1234)',
data: [{
data: {
keyword: 'Related: ',
id: 'RHELPLAN-1234',
type: 'jira',
url: 'https://issues.redhat.com/browse/RHELPLAN-1234',
},
}],
}Object that describes all upstreams detected in commit message and their validation status.
upstream: {
data: [{
sha: 'b145cbd729d33cc50d299079a9a5c643531ad053',
repo: 'systemd/systemd',
url: 'https://github.com/systemd/systemd/commit/b145cbd729d33cc50d299079a9a5c643531ad053',
}],
status: 'success',
exception: 'rhel-only',
}Object that describes overall validation status of all commits in Pull Request.
validation: {
status: 'success',
tracker: {
message: 'Tracker found',
type: 'unknown',
id: 'RHELPLAN-1234',
url: 'https://issues.redhat.com/browse/RHELPLAN-1234',
},
message:
'Tracker - [RHELPLAN-1234](https://issues.redhat.com/browse/RHELPLAN-1234)\
\
#### The following commits meet all requirements\
\
| commit | upstream |\
|---|---|\
| https://github.com/redhat-plumbers-in-action/advanced-commit-linter/commit/b145cbd729d33cc50d299079a9a5c643531ad053 - _fix: typo_ | `rhel-only` |',
}![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
![renovate[bot] avatar](https://avatars.githubusercontent.com/in/2740?v=4 "renovate[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent