Git hook for Jira workflow
npm install git-jira-hookEnforces commit messages and branches to be written in a specific format (using JIRA), following a similar structure to the conventional commits. This is done through husky and the commit-msg hook.
``
npm i -D git-jira-hook
`
"husky": {
"hooks": {
"commit-msg": "git-jira-hook ${HUSKY_GIT_PARAMS} --projectId MYPROJ"
}
},
on Husky 5 (commit-msg):
`
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
npx git-jira-hook $1
`
The hook will validate two things:
- That the current branch is valid to commit directly, and has the correct format.
- That the commit message has the correct format.
Without a configuration file, all validations will work with its default value.
All these validations can be skipped by adding the --no-verify (or -n) flag when commiting.
The branch should contain its type, a Jira ticket (when required) and an optional description. The pattern is as follows:
[branch-type]/JIRA-ticket
In order to support additional branch types, they must be added through a configuration file.
By default, there are 2 "main" branches, where direct commits are not allowed: master and develop.
By default, there are 3 "non-ticket" branch prefixes: other, release, and support.
Examples of valid non-ticket branches:
- other/update-configuration
-
By default, there are 3 "ticket" branch prefixes: feature, bugfix, and hotfix. These branches require a Jira ticket in its name, otherwise the commit will be rejected. A description can be included after the Jira ticket, followed by a hyphen (-).
Examples of valid ticket branches:
- feature/MYPROJ-13
-
Examples of invalid ticket branch types:
- feature/TEST-123_Optional-Description
The commit message must have a valid prefix, a Jira ticket associated and a message. If the Jira ticket is omitted, the hook will try and add it based on the ticket in the branch name (when applicable). The pattern is as follows:
commit-type: [message]
In order to support additional commit types, they must be added through a configuration file.
By default, there is only one "non-ticket" commit type: other. This means that a JIRA ticket is not required.
Examples of valid non-ticket commit messages:
- other: Updated configuration
By default, there are 3 commit types allowed: feat, fix and chore. These commits must include a JIRA ticket. If ommited, the hook will try and add it based on the branch name (when applicable).
Examples of valid ticket commit messages (with a Jira ticket):
- feat(PROJ-13): Add Settings page
-
Example of valid ticket commit messages (without a Jira ticket):
- feat: Add Home page
The hook will identify special commit messages. These commit messages will always be allowed regarding on format or branch, except for the main branches.
The hook will allow special commits such as:
1. Commits generated during a merge (e.g. Merge dev-branch...).1.2.0
2. Messages with just the app's version (e.g. , v1.2.0, v1.2.1-beta.1, etc.).BREAKING CHANGES
3. commits.
For minimal configuration, you just need to pass projectId on the commit-msg hook file. This will be used to ensure that all tickets are based on this id.
`
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
npx git-jira-hook $1 --projectId MYPROJ
`
Based on the configuration above, the following are correct:
- feat(MYPROJ-10): Commit message
-
You can create a config file to override default constants, it can be a JSON file. or a JS file either exporting an object or a function that return an object.
When adding a configuration file, only projectId is required.
The following is an example of a full configuration file, with the default values:
`json`
{
"projectId": "MYPROJ",
"commitTypes": {
"ticket": ["feat", "feature", "fix"],
"nonTicket": ["chore", "refactor"]
},
"branchTypes": {
"main": ["master"],
"ticket": ["feat", "feature", "bugfix"],
"nonTicket": ["release", "support"]
}
}
By default it will look for hooks.config.js or hooks.config.json on the root folder. You can also specify a custom path and name:
`
"husky": {
"hooks": {
"commit-msg": "git-jira-hook ${HUSKY_GIT_PARAMS} --config 'path/to/my-jira-config.js'"
}
},
on Husky 5 (commit-msg):
`
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
npx git-jira-hook $1 --config 'path/to/my-jira-config.js'
`
The commit-msg hook does job. First, it will check that the message has the correct format. If so, it will check if the ticket is on the message (if required). If the ticket is not there and is required (i.e. the ticket is not present on a feat commit type), it will check if the ticket is available on the branch name. If so, it will append it:
feat: Do stuff -> feat(PROJ-66): Do stuff
Not complying with these conditions will abort the commit. It will display a message on what did fail:
!log
Important: These messages show up when commiting from the terminal. If using, for example, VS Code's Source Control, it will show up an alert with a Open git log option when an error occurs, where the same messages can be seen (in an uglier format).
`shellcommit-msgcreate a file named
npx git-jira-hook commit-msg --debug
Additionally:
1. Build with npm run build
2. Run test on
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.