advanced-commit-linter
v2.1.0
Published
Lint commit messages based on policy
Downloads
10
Maintainers
Readme
Advanced Commit Linter is a GitHub Action that lint commit messages of PR. It checks for issue trackers and upstream references. Results are displayed as a status check and Pull Request comment.
How does it work
TBA
Features
- Tracker references validator
- Upstream references (cherry-pick) validator
- Summary comment on Pull Request
Usage
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-run
trigger, downloads artifact, and runsadvanced-commit-linter
GitHub Action advanced-commit-linter.yml
configuration
Note: Setup is complicated due to GitHub permissions on
GITHUB_TOKEN
. When used in workflow executed from fork it hasread-only
permissions. By using theworkflow-run
trigger 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-only
name: 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
# required for PR comments
pull-requests: 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 }}
Configuration options
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>
token: <GitHub token or PAT>
# ...
pr-metadata
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
config-path
Path to configuration file. Configuration file format is described in: Policy section.
- default value:
.github/advanced-commit-linter.yml
- requirements:
optional
token
GitHub token or PAT is used for creating comments on Pull Request and setting checks.
# required permission
permissions:
checks: write
pull-requests: write
- default value:
undefined
- requirements:
required
- recomended value:
secrets.GITHUB_TOKEN
Policy
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:
- 'JIRA-1234'
url: 'https://issues.redhat.com/browse/'
exception:
note:
- github-only
cherry-pick
keyword
The section that specifies upstreams for which you frequently cherry-pick.
- requirements:
optional
cherry-pick.upstream
keyword
An array of upstreams. Currently, the only supported upstream location is GitHub.
Supported keys:
github
- GitHub repository in format<org>/<repo>
- requirements:
required
cherry-pick.exception
keyword
Property that describes possible exceptions for referencing upstream commits in commit messages. Currently supported exceptions:
note
- for exampledownstream-only
orrhel-only
tracker
keyword
The section specifies the form and type of required trackers.
tracker[].keyword
keyword
Keyword that prefixes tracker identificator.
- requirements:
required
- example:
Fixes:
tracker[].type
keyword
Type of tracker. Data can be used by postprocessing scripts/GitHub Actions.
Currently supproted types of trackers are: bugzilla
, jira
and unknown
.
- requirements:
required
tracker[].issue-format
keyword
Regex that describes identificator of given tracker.
- requirements:
required
- example:
[0-9]+$
tracker[].url
keyword
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/
tracker[].exception
keyword
Property that describes possible exceptions for referencing trackers in commit messages. Currently supported exceptions:
note
- for examplegithub-only
ortests-only
Outputs
validated-pr-metadata
TBA